Observability

tsiam emits structured logs and metrics via OpenTelemetry, making it straightforward to integrate with any modern observability stack.

Logs#

Logs include contextual fields such as trace IDs and span IDs for correlation with distributed traces.

Configure the log level in config.yaml:

logs:
  # debug, info, warn, error
  level: info
  # Suppress /healthz log lines (default: true)
  omitHealthChecks: true
  # Force JSON output (auto-detected based on TTY when not set)
  json: true

To ship logs to an OpenTelemetry collector, set OTEL_EXPORTER_OTLP_ENDPOINT. No additional config is needed.

Metrics#

To export metrics to an OpenTelemetry collector:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_SERVICE_NAME=tsiam
export OTEL_RESOURCE_ATTRIBUTES=environment=production,region=us-east-1

To expose a Prometheus-compatible scrape endpoint instead:

export OTEL_METRICS_EXPORTER=prometheus
export OTEL_EXPORTER_PROMETHEUS_PORT=9464

This starts a /metrics endpoint on the configured port that Prometheus can scrape.

OpenTelemetry environment variables#

Variable	Description	Default
`OTEL_SDK_DISABLED`	Disable OpenTelemetry entirely	`false`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP collector endpoint	—
`OTEL_EXPORTER_OTLP_PROTOCOL`	Protocol: `grpc` or `http/protobuf`	`http/protobuf`
`OTEL_LOGS_EXPORTER`	Logs exporter: `otlp`, `console`, `none`	`otlp`
`OTEL_METRICS_EXPORTER`	Metrics exporter: `otlp`, `prometheus`, `console`, `none`	`otlp`
`OTEL_EXPORTER_PROMETHEUS_HOST`	Host for Prometheus endpoint	`localhost`
`OTEL_EXPORTER_PROMETHEUS_PORT`	Port for Prometheus endpoint	`9464`
`OTEL_SERVICE_NAME`	Service name in telemetry	`tsiam`
`OTEL_RESOURCE_ATTRIBUTES`	Additional resource attributes	—

For a complete list, see the OpenTelemetry SDK configuration docs .

Example: Docker with OpenTelemetry Collector#

docker run -d \
  --name tsiam \
  -v /path/to/config.yaml:/etc/tsiam/config.yaml:ro \
  -v /path/to/tsnet-state:/etc/tsiam/tsnet \
  -v /path/to/tsiam-state:/var/lib/tsiam \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
  -e OTEL_SERVICE_NAME=tsiam \
  -e OTEL_RESOURCE_ATTRIBUTES=environment=production \
  ghcr.io/italypaleale/tsiam:v0

tsiam works with any OpenTelemetry-compatible backend, including Grafana Cloud, Datadog, Honeycomb, and self-hosted collectors.