Logging and observability

Configure logging, distributed tracing, and metrics for the self-hosted io.sign backend

The self-hosted io.sign backend writes structured logs, exports traces and metrics through OpenTelemetry, and exposes health check endpoints. Set the environment variables on this page on the backend described in Configuration.

Logging

LOG_LEVEL=info
LOG_PRETTY=false

io.sign writes JSON logs to standard output, one line per entry, so any log collector can read them. Each entry carries the trace ID of the request it belongs to. LOG_PRETTY=true prints readable logs instead; use it locally only.

The service never logs secrets. It redacts authorisation headers, cookies, passwords, tokens, secrets, keys, credentials, and certificates. HTTP logs include request and response bodies up to HTTP_LOG_MAX_BODY_BYTES, 64 KiB by default.

Observability

io.sign uses OpenTelemetry (OTEL) for distributed tracing and metrics across all four components. Point the service at an OpenTelemetry Protocol (OTLP) collector:

OTEL_EXPORTER_OTLP_ENDPOINT=http://<collector-host>:4318
OTEL_SERVICE_NAME=io-sign
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

The service auto-instruments incoming REST and gRPC requests, PostgreSQL queries, Redis operations, outgoing HTTP calls such as JWKS fetches, and TLS handshakes.

Give each component its own service name so you can tell them apart:

ComponentOTEL_SERVICE_NAME
REST APIio-sign-rest
gRPC APIio-sign-grpc
Orchestratorio-sign-orchestrator
Cronio-sign-cron
Webhooks serviceio-sign-webhooks
VariableRequiredDefaultDescription
OTEL_EXPORTER_OTLP_ENDPOINTYesnoneOTLP collector endpoint, for example http://localhost:4318
OTEL_SERVICE_NAMEYesnoneService name for trace identification, for example io-sign-rest
OTEL_RESOURCE_ATTRIBUTESNononeExtra resource attributes, for example deployment.environment=prod
OTEL_TRACES_SAMPLERNoparentbased_always_onSampling strategy. Use parentbased_traceidratio in production
OTEL_TRACES_SAMPLER_ARGNo1.0Sampling ratio from 0.0 to 1.0. Set to 0.1 for 10% sampling in production
OTEL_TRACES_EXPORTERNootlpSet to none to disable trace export
OTEL_METRICS_EXPORTERNootlpSet to none to disable metric export
OTEL_INSTRUMENTATION_HTTP_IGNORE_INCOMING_REQUEST_URLSNononeComma-separated request paths to leave out of tracing, for example /v2/health/check, so health checks don't flood your traces
OTEL_EVENT_PROPAGATIONNofalseCarries trace context through io.sign's internal events, so a trace follows a request from the API to the orchestrator

To disable telemetry export entirely, for example in local development without a collector:

OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=none

Health checks

Point your load balancer and container platform at these endpoints:

ComponentCheckHealthy response
REST APIGET /v2/health/check on port 3000200 with a JSON body whose status is healthy
gRPC APIGET /health over HTTP/2 on port 50051200 with {"status":"healthy","server":"grpc"}
Webhooks serviceGET /v1/webhooks/health on port 3010200

The REST health response also reports the database connection, and the running version and commit. Check the body, not only the status code: a path without the /v2 prefix also returns 200, with the API playground's HTML.


Did this page help you?