opentelemetry-instrumentation

OpenTelemetry SDK Instrumentation for Coralogix

When to Use This Skill

Use case	What to do
Choose a language / decide where to start	Load language-selector.md first — it has the decision tree for language, signal, mode, and export path
Generate setup for a specific language	Load the language reference after confirming the SDK: java.md, python.md, nodejs.md, dotnet.md, go.md
Configure OTLP endpoint, region, or authentication	Load coralogix-endpoints.md — covers regional domains, OTLP host:port, auth header format
Generate a complete user-facing answer	Load output-templates.md — checklist structure with assumptions, code, validation steps
Diagnose missing traces, metrics, or logs from the SDK	Load troubleshooting.md — symptom → root-cause table for SDK-side failures

Load order: language-selector.md → language ref → coralogix-endpoints.md → output-templates.md (always last). Load troubleshooting.md only for debugging.

Answer Rules

Before answering (agent mode):

• Always call list_references() first, then read_reference(...) for the relevant files (language selector + the target language + endpoints; add troubleshooting only when debugging). Do not answer from memory if the references could affect correctness.
• Use the structure/checklists in output-templates.md for any user-facing response; keep your own prose minimal and actionable.

Always include in generated answers:

• Required env vars (names only) — include these in any “copy/paste” setup: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES (plus OTEL_*_EXPORTER / OTEL_EXPORTER_OTLP_*_PROTOCOL when choosing signals/protocol). For exact per-language endpoint formats and the Python %20 env-var rule, use coralogix-endpoints.md.

• Required resource attributes — service.name (APM catalog/transactions), cx.application.name + cx.subsystem.name (routing, TCO, APM grouping), telemetry.sdk.language (auto-set; do not strip). Missing any silently degrades APM. Additional k8s/host attributes are covered in each language reference.

• Telemetry quality. Low-cardinality span names, no sensitive data, bounded metric attributes, structured single-line logs with trace/span IDs, validation steps for the signal. Never approve user-scoped values (user_id, tenant_id, request_id, session_id) as metric labels — they cause unbounded cardinality and will explode metric storage.

• Direct vs collector routing rule: Default to direct OTLP for dev/test environments, simple single-service production deployments, or when no collector infrastructure exists. Default to via-collector for Kubernetes workloads needing pod/namespace enrichment (k8sattributes), tail sampling, multi-service shared key management, or buffered retry/file persistence requirements. When the deployment context is unknown, show both options using the tradeoff table in language-selector.md.

• Collector config is out of scope. Redirect to opentelemetry-collector — do not partially answer pipeline or processor questions.

High-Risk Gotchas (Do Not Guess)

Keep this list short and only use it when the user’s symptom matches. For details, defer to the language references.

• Java agent: opentelemetry-javaagent.jar + JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar".
• Java/.NET gRPC endpoint: must be a full URI https://ingress.<region>.coralogix.com:443 (URI parsing breaks bare host:port).
• Python auth header: env var needs %20 (Authorization=Bearer%20<KEY>); programmatic headers use a tuple sequence with lowercase key + literal space (("authorization", f"Bearer {token}")).
• Node.js HTTP/proto: exporter url must include /v1/traces (https://ingress.<region>.coralogix.com:443/v1/traces); gRPC doesn’t.
• Go gRPC: credentials.NewTLS(nil) and bare endpoint ingress.<region>.coralogix.com:443 (no https:// in WithEndpoint).
• Go metrics cardinality: sdk/metric defaults to a cardinality limit of 2000; use WithCardinalityLimit(0) only when you intentionally need unlimited series, and expect otel.metric.overflow=true when the limit is hit.
• .NET OTLP disk retry: OTEL_DOTNET_EXPERIMENTAL_OTLP_RETRY=disk now requires OTEL_DOTNET_EXPERIMENTAL_OTLP_DISK_RETRY_DIRECTORY_PATH; do not rely on an implicit temp-directory fallback.
• Transactions: require CoralogixTransactionSampler (Node.js: @coralogix/opentelemetry); bundled NODE_OPTIONS auto-instr doesn’t support Transactions.
• Short-lived Python scripts: SimpleSpanProcessor vs BatchSpanProcessor; metrics need PeriodicExportingMetricReader flush/wait.
• .NET Framework incoming propagation: OpenTelemetry.Instrumentation.AspNet + AddAspNetInstrumentation().

Workflow

• New setup: language-selector.md → language ref + coralogix-endpoints.md → generate with output-templates.md.
• Code review: language ref → review checklist in output-templates.md.
• Debugging: troubleshooting.md first; escalate to language ref only if SDK-side cause confirmed.

Limitations

• OTel Collector / OTTL — use opentelemetry-collector or opentelemetry-ottl.
• Lambda / serverless — use Coralogix Lambda layer docs; Payload Too Large OTLP errors are Lambda-layer concerns, not SDK.
• PHP, eBPF auto-instrumentation — not covered.
• Coralogix platform internals (data routing, index policies, APM UI config) — platform topics.

Deprecated native SDKs

Native Coralogix SDKs are EOL June 30, 2026 — redirect to OTel and do not provide configuration for legacy packages.

Upstream references

Coralogix OTel instrumentation: Java · Python · Node.js · .NET · Go

Coralogix OTel docs · OpenTelemetry official docs