kopai/otel-instrumentation
Instrument applications with the OpenTelemetry SDK and prove the telemetry is good by validating it against a local Kopai backend. Use when setting up observability, adding tracing/logging/metrics, deciding what to instrument or which attributes to add, retrofitting OTel into an existing codebase, threading context through call chains, configuring sampling, or when traces/logs/metrics aren't appearing after setup. Also use when users say things like "my traces aren't showing up", "I don't see any data", or "how do I add observability to my app". Do NOT use to investigate existing telemetry for a root cause (use root-cause-analysis), to build dashboards (use create-dashboard), or to instrument LLM and agent calls (use otel-genai-instrumentation).
—
—
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Low
Low-risk findings worth noting
troubleshoot-wrong-port.mdreferences/
| title | impact | tags |
|---|---|---|
| Wrong Port | MEDIUM | troubleshoot, port |
Wrong Port
Kopai runs two servers, and sending telemetry to the wrong one produces silence rather than an error.
| Port | Service | Direction |
|---|---|---|
| 4318 | OTEL collector | Your app sends telemetry here (OTLP/HTTP) |
| 8000 | API server | The CLI and SDK read data from here |
# WRONG — the API server does not accept OTLP
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:8000
# CORRECT
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318Port 4317 is also wrong: that is the conventional gRPC port, and Kopai is HTTP-only.
A Go or Java SDK left on its default will try it — setup-environment.md covers forcing
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.
Verify both ends
# collector accepts OTLP
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4318/v1/traces \
-H 'Content-Type: application/json' -d '{"resourceSpans":[]}'
# API server answers queries
curl -s http://localhost:8000/signals/traces | head -c 200Check the endpoint in the shell that launched the app. A correction exported afterwards never reaches the running process — restart it.
references