Skip to content

feat(telemetry): add OpenTelemetry traces and metrics #792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tobiasehlert merged 5 commits into from
Oct 21, 2026
Merged

feat(telemetry): add OpenTelemetry traces and metrics #792

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8409339
feat(telemetry): add OpenTelemetry traces and metrics
tobiasehlert Oct 21, 2026
9d05112
refactor(telemetry): pass context directly to collectors
tobiasehlert Oct 21, 2026
dd526dc
perf(telemetry): skip SDK providers for disabled exporters
tobiasehlert Oct 21, 2026
a0f4267
fix(server): handle SIGTERM for graceful shutdown
tobiasehlert Oct 21, 2026
6acdba0
fix(server): drain requests on shutdown and gate telemetry hooks
tobiasehlert Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,7 @@ The following environment variables can be used to configure the API.
| `TIBIADATA_LOG_CF_RAY` | `false` | Logs Cloudflare's `Cf-Ray` header as `request_id` when `true`. Enable only when the API is reachable exclusively through Cloudflare. |
| `TIBIADATA_LOG_FORMAT` | `text` | Log output format: `text` or `json`. |
| `TIBIADATA_LOG_LEVEL` | `info` (or `debug` when `DEBUG_MODE=true` and unset) | Application log level: `debug`, `info`, `warn`, `error`. |
| `TIBIADATA_OTEL_ENABLED` | `false` | Enables OpenTelemetry traces and metrics (see [OpenTelemetry](#opentelemetry)). |
| `TIBIADATA_PROTOCOL` | `https` | Protocol used together with `TIBIADATA_HOST` when generating API URLs. |
| `TIBIADATA_PROXY` | `www.tibia.com` | Domain to fetch data from instead of `www.tibia.com`, e.g. a caching proxy. |
| `TIBIADATA_PROXY_PROTOCOL` | `https` | Protocol for `TIBIADATA_PROXY` (`http` or `https`). Only used when `TIBIADATA_PROXY` is set. |
Expand All @@ -137,6 +138,39 @@ The following environment variables can be used to configure the API.

Set `TIBIADATA_LOG_CF_RAY=true` to log Cloudflare's `Cf-Ray` header as `request_id` when present. Restrict origin access to Cloudflare so that clients cannot send arbitrary `Cf-Ray` values directly to the API.

### OpenTelemetry

Set `TIBIADATA_OTEL_ENABLED=true` to enable [OpenTelemetry](https://opentelemetry.io/) traces and metrics. When enabled, the API:

- creates a server span for each incoming request and continues traces from incoming W3C `traceparent` headers,
- creates client spans for upstream requests (e.g. to tibia.com) and propagates the trace context to them,
- records HTTP server and client metrics such as `http.server.request.duration` (request count, latency, method, route and status code),
- adds `trace_id` and `span_id` to request logs, so logs can be correlated with traces.

Probe endpoints (`/ping`, `/health`, `/healthz`, `/readyz`) are included in metrics but not traced.

All other settings use the standard [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/), for example:

| Variable | Default | Description |
| --- | --- | --- |
| `OTEL_SERVICE_NAME` | `tibiadata-api-go` | Service name reported in telemetry. |
| `OTEL_RESOURCE_ATTRIBUTES` | _(empty)_ | Additional resource attributes, e.g. `deployment.environment=production`. |
| `OTEL_TRACES_EXPORTER` | `otlp` | Trace exporter: `otlp`, `console` or `none`. |
| `OTEL_METRICS_EXPORTER` | `otlp` | Metrics exporter: `otlp`, `prometheus`, `console` or `none`. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | OTLP collector endpoint. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `http/protobuf` | OTLP protocol: `http/protobuf` or `grpc`. |
| `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | Trace sampler, e.g. `parentbased_traceidratio` together with `OTEL_TRACES_SAMPLER_ARG=0.1`. |
| `OTEL_EXPORTER_PROMETHEUS_HOST` / `OTEL_EXPORTER_PROMETHEUS_PORT` | `localhost` / `9464` | Listen address of the Prometheus `/metrics` endpoint when `OTEL_METRICS_EXPORTER=prometheus`. Set the host to `0.0.0.0` to expose it outside the container. |

A signal whose exporter is set to `none` creates no spans or measurements. When telemetry is disabled, or both exporters are `none`, no instrumentation is installed at all. For example, to collect only metrics:

```bash
TIBIADATA_OTEL_ENABLED=true
OTEL_TRACES_EXPORTER=none
OTEL_METRICS_EXPORTER=prometheus
OTEL_EXPORTER_PROMETHEUS_HOST=0.0.0.0
```

### Deployment note

You should consider to add a layer in front of this application, so you can do caching of endpoints, access controll or what ever your needs are.
Expand Down
71 changes: 56 additions & 15 deletions go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,40 +17,81 @@ require (
github.com/stretchr/testify v1.12.1
github.com/tibiadata/tibiadata-api-go/src/static v0.0.0-20260708000506-76c8bf3494d0
github.com/tibiadata/tibiadata-api-go/src/validation v0.0.0-20260708000506-76c8bf3494d0
go.opentelemetry.io/contrib/exporters/autoexport v0.72.0
go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin v0.72.0
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.72.0
go.opentelemetry.io/otel v1.47.0
go.opentelemetry.io/otel/sdk v1.47.0
go.opentelemetry.io/otel/sdk/metric v1.47.0
go.opentelemetry.io/otel/trace v1.47.0
golang.org/x/net v0.61.0
golang.org/x/text v0.43.0
)

require (
github.com/andybalholm/cascadia v1.3.4 // indirect
github.com/beorn7/perks v1.0.1 // indirect
github.com/bytedance/gopkg v0.1.4 // indirect
github.com/bytedance/sonic v1.15.2 // indirect
github.com/bytedance/sonic/loader v0.5.1 // indirect
github.com/bytedance/sonic v1.15.4 // indirect
github.com/bytedance/sonic/loader v0.5.2 // indirect
github.com/cenkalti/backoff/v5 v5.0.3 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
github.com/cloudwego/base64x v0.1.7 // indirect
github.com/gabriel-vasile/mimetype v1.4.13 // indirect
github.com/gin-contrib/sse v1.1.1 // indirect
github.com/go-playground/locales v0.14.1 // indirect
github.com/go-playground/universal-translator v0.18.1 // indirect
github.com/go-playground/validator/v10 v10.30.3 // indirect
github.com/goccy/go-json v0.10.6 // indirect
github.com/felixge/httpsnoop v1.1.0 // indirect
github.com/gabriel-vasile/mimetype v1.4.15 // indirect
github.com/gin-contrib/sse v1.1.2 // indirect
github.com/go-logr/logr v1.4.4 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-playground/locales v0.14.2 // indirect
github.com/go-playground/universal-translator v0.18.2 // indirect
github.com/go-playground/validator/v10 v10.30.5 // indirect
github.com/goccy/go-json v0.11.2 // indirect
github.com/goccy/go-yaml v1.19.2 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.31.0 // indirect
github.com/json-iterator/go v1.1.12 // indirect
github.com/klauspost/cpuid/v2 v2.4.0 // indirect
github.com/leodido/go-urn v1.4.0 // indirect
github.com/mattn/go-isatty v0.0.23 // indirect
github.com/leodido/go-urn v1.5.0 // indirect
github.com/mattn/go-isatty v0.0.24 // indirect
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
github.com/modern-go/reflect2 v1.0.2 // indirect
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
github.com/pelletier/go-toml/v2 v2.4.3 // indirect
github.com/projectbarks/cimap v0.1.1 // indirect
github.com/prometheus/client_golang v1.24.1 // indirect
github.com/prometheus/client_model v0.6.3 // indirect
github.com/prometheus/common v0.72.0 // indirect
github.com/prometheus/otlptranslator v1.0.0 // indirect
github.com/prometheus/procfs v0.22.0 // indirect
github.com/quic-go/qpack v0.6.0 // indirect
github.com/quic-go/quic-go v0.60.0 // indirect
github.com/quic-go/quic-go v0.63.0 // indirect
github.com/tibiadata/tibiadata-api-go/src/tibiamapping v0.0.0-20260707225952-a0db793b45fa // indirect
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
github.com/ugorji/go/codec v1.3.1 // indirect
go.mongodb.org/mongo-driver/v2 v2.8.0 // indirect
github.com/ugorji/go/codec v1.3.2 // indirect
go.mongodb.org/mongo-driver/v2 v2.9.1 // indirect
go.opentelemetry.io/auto/sdk v1.2.1 // indirect
go.opentelemetry.io/contrib/bridges/prometheus v0.72.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.23.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp v0.23.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc v1.47.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp v1.47.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.47.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.47.0 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.47.0 // indirect
go.opentelemetry.io/otel/exporters/prometheus v0.69.0 // indirect
go.opentelemetry.io/otel/exporters/stdout/stdoutlog v0.23.0 // indirect
go.opentelemetry.io/otel/exporters/stdout/stdoutmetric v1.47.0 // indirect
go.opentelemetry.io/otel/exporters/stdout/stdouttrace v1.47.0 // indirect
go.opentelemetry.io/otel/log v1.47.0 // indirect
go.opentelemetry.io/otel/metric v1.47.0 // indirect
go.opentelemetry.io/otel/sdk/log v1.47.0 // indirect
go.opentelemetry.io/proto/otlp v1.11.1 // indirect
go.yaml.in/yaml/v3 v3.0.5 // indirect
golang.org/x/arch v0.29.0 // indirect
golang.org/x/arch v0.31.0 // indirect
golang.org/x/crypto v0.58.0 // indirect
golang.org/x/sys v0.49.0 // indirect
google.golang.org/protobuf v1.36.11 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20260928230214-8a89bd6388cc // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260928230214-8a89bd6388cc // indirect
google.golang.org/grpc v1.84.0 // indirect
google.golang.org/protobuf v1.36.12 // indirect
)
Loading
Loading