peren
Menu
Search Peren documentation
Start typing to search the documentation.
    Browse documentation
    On this page
    Search Peren documentation
    Start typing to search the documentation.

      Peren documentation

      Observability

      Use health, readiness, metrics, logs, and tail on a running Peren node.

      Observe a node through health endpoints, Prometheus metrics, local logs, local lifecycle traces, and optional OTLP trace export.

      Operator signals

      The node emits health, metrics, and a local tail. THIS NODE EMITTED SIGNALS reads Peren node /healthz /readyz /metrics local tail log peren tail

      Endpoints that work

      On configured listeners:

      Path Meaning
      /healthz Process is alive. Always 200 when the listener answers.
      /readyz Listener is ready for traffic. Returns 200 or 503.
      /metrics Prometheus text exposition of process and runtime series.

      An operator may scrape /metrics with Prometheus. That choice belongs to the operator’s monitoring stack. Peren does not ship Grafana dashboards as a product feature.

      curl -sS http://127.0.0.1:8080/healthz
curl -sS http://127.0.0.1:8080/readyz
curl -sS http://127.0.0.1:8080/metrics

      Metric names and HELP text are listed in Metrics reference.

      Logs, tail, and traces

      peren logs and peren tail read the same local event stream for one service. --service is required. There is no --kind flag.

      peren tail peren.toml --service api --level error
peren logs peren.toml --service api --level warn

      Optional --level is log, warn, or error. Request events print method, path, status, outcome, and wall time. Console events print Worker console severity and message.

      Representative request line:

      api POST /checkout status=500 outcome=error wall_time_ms=37

      Representative console line:

      api console Error checkout failed

      peren trace reads the local lifecycle trace stream from ${PEREN_DATA_DIR}/traces/events.jsonl. Filter by service, request id, or trace id:

      peren trace peren.toml --service api --request-id request-123
peren trace peren.toml --trace-id 4bf92f3577b34da6a3ce929d0e0e4736 --json

      Lifecycle traces include cell.restore, cell.dispatch, cell.commit, and cell.release spans for Worker dispatch. Service binding fetches record service.fetch, and Durable Object fetches record durable_object.fetch; child dispatches keep the same trace id through those boundaries.

      The local trace file rotates at 64 MiB. Peren keeps the active file and one previous segment, events.jsonl.1; older local trace events are discarded. Use OTLP export when traces need longer retention.

      OTLP export

      Add [otlp] to export sampled lifecycle spans to an OTLP HTTP trace endpoint. Export is best effort. Collector failures do not stop Worker dispatch, and Peren keeps appending local trace JSONL while the collector is down.

      [tracing]
sampling_ratio = 1.0

[otlp]
endpoint = "https://collector.example.com/v1/traces"
service_name = "peren-node"
batch_max_spans = 128
flush_interval_secs = 5
request_timeout_secs = 10

[otlp.headers]
authorization = "Bearer replace-with-token"

      Set sampling_ratio = 0.0 to disable span recording, or a value between 0.0 and 1.0 to sample incoming traces.

      Config that fails validation

      [logpush] fails config validation in this build. Use [otlp] for trace export.

      Related: Metrics reference, Operations overview, Degraded operation.