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=falseio.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=productionThe 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:
| Component | OTEL_SERVICE_NAME |
|---|---|
| REST API | io-sign-rest |
| gRPC API | io-sign-grpc |
| Orchestrator | io-sign-orchestrator |
| Cron | io-sign-cron |
| Webhooks service | io-sign-webhooks |
| Variable | Required | Default | Description |
|---|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | Yes | none | OTLP collector endpoint, for example http://localhost:4318 |
OTEL_SERVICE_NAME | Yes | none | Service name for trace identification, for example io-sign-rest |
OTEL_RESOURCE_ATTRIBUTES | No | none | Extra resource attributes, for example deployment.environment=prod |
OTEL_TRACES_SAMPLER | No | parentbased_always_on | Sampling strategy. Use parentbased_traceidratio in production |
OTEL_TRACES_SAMPLER_ARG | No | 1.0 | Sampling ratio from 0.0 to 1.0. Set to 0.1 for 10% sampling in production |
OTEL_TRACES_EXPORTER | No | otlp | Set to none to disable trace export |
OTEL_METRICS_EXPORTER | No | otlp | Set to none to disable metric export |
OTEL_INSTRUMENTATION_HTTP_IGNORE_INCOMING_REQUEST_URLS | No | none | Comma-separated request paths to leave out of tracing, for example /v2/health/check, so health checks don't flood your traces |
OTEL_EVENT_PROPAGATION | No | false | Carries 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=noneHealth checks
Point your load balancer and container platform at these endpoints:
| Component | Check | Healthy response |
|---|---|---|
| REST API | GET /v2/health/check on port 3000 | 200 with a JSON body whose status is healthy |
| gRPC API | GET /health over HTTP/2 on port 50051 | 200 with {"status":"healthy","server":"grpc"} |
| Webhooks service | GET /v1/webhooks/health on port 3010 | 200 |
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.
Updated 17 days ago