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
1---2name: opentelemetry-instrumentation3description: Instruments Java, Python, Node.js, .NET, and Go applications with OpenTelemetry SDKs to send traces, metrics, and logs to Coralogix. Use for SDK-side OTel setup, OTLP exporter env vars, Coralogix resource attributes, APM transaction samplers, Kubernetes Operator injection, or debugging missing traces, metrics, logs, or no telemetry from an application. Not for OTel Collector config (use opentelemetry-collector), OTTL authoring (use opentelemetry-ottl), eBPF instrumentation, or Lambda layers.4license: Apache-2.05---67# OpenTelemetry SDK Instrumentation for Coralogix89## When to Use This Skill1011| Use case | What to do |12|---|---|13| Choose a language / decide where to start | Load [language-selector.md](references/language-selector.md) first — it has the decision tree for language, signal, mode, and export path |14| Generate setup for a specific language | Load the language reference after confirming the SDK: [java.md](references/java.md), [python.md](references/python.md), [nodejs.md](references/nodejs.md), [dotnet.md](references/dotnet.md), [go.md](references/go.md) |15| Configure OTLP endpoint, region, or authentication | Load [coralogix-endpoints.md](references/coralogix-endpoints.md) — covers regional domains, OTLP host:port, auth header format |16| Generate a complete user-facing answer | Load [output-templates.md](references/output-templates.md) — checklist structure with assumptions, code, validation steps |17| Diagnose missing traces, metrics, or logs from the SDK | Load [troubleshooting.md](references/troubleshooting.md) — symptom → root-cause table for SDK-side failures |1819Load order: [language-selector.md](references/language-selector.md) → language ref → [coralogix-endpoints.md](references/coralogix-endpoints.md) → [output-templates.md](references/output-templates.md) (always last). Load [troubleshooting.md](references/troubleshooting.md) only for debugging.2021## Answer Rules2223Before answering (agent mode):2425- **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.26- **Use the structure/checklists in [output-templates.md](references/output-templates.md)** for any user-facing response; keep your own prose minimal and actionable.2728Always include in generated answers:2930- **Required env vars (names only)** — include these in any “copy/paste” setup:31 `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES`32 (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](references/coralogix-endpoints.md).3334- **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.3536- **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.37- **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](references/language-selector.md).38- **Collector config is out of scope.** Redirect to `opentelemetry-collector` — do not partially answer pipeline or processor questions.3940## High-Risk Gotchas (Do Not Guess)4142Keep this list short and only use it when the user’s symptom matches. For details, defer to the language references.4344- **Java agent:** `opentelemetry-javaagent.jar` + `JAVA_TOOL_OPTIONS="-javaagent:/path/to/opentelemetry-javaagent.jar"`.45- **Java/.NET gRPC endpoint:** must be a full URI `https://ingress.<region>.coralogix.com:443` (URI parsing breaks bare `host:port`).46- **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}")`).47- **Node.js HTTP/proto:** exporter `url` must include `/v1/traces` (`https://ingress.<region>.coralogix.com:443/v1/traces`); gRPC doesn’t.48- **Go gRPC:** `credentials.NewTLS(nil)` and bare endpoint `ingress.<region>.coralogix.com:443` (no `https://` in `WithEndpoint`).49- **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.50- **.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.51- **Transactions:** require `CoralogixTransactionSampler` (Node.js: `@coralogix/opentelemetry`); bundled `NODE_OPTIONS` auto-instr doesn’t support Transactions.52- **Short-lived Python scripts:** `SimpleSpanProcessor` vs `BatchSpanProcessor`; metrics need `PeriodicExportingMetricReader` flush/wait.53- **.NET Framework incoming propagation:** `OpenTelemetry.Instrumentation.AspNet` + `AddAspNetInstrumentation()`.5455## Workflow5657- **New setup:** [language-selector.md](references/language-selector.md) → language ref + [coralogix-endpoints.md](references/coralogix-endpoints.md) → generate with [output-templates.md](references/output-templates.md).58- **Code review:** language ref → review checklist in [output-templates.md](references/output-templates.md).59- **Debugging:** [troubleshooting.md](references/troubleshooting.md) first; escalate to language ref only if SDK-side cause confirmed.6061## Limitations6263- **OTel Collector / OTTL** — use `opentelemetry-collector` or `opentelemetry-ottl`.64- **Lambda / serverless** — use Coralogix Lambda layer docs; `Payload Too Large` OTLP errors are Lambda-layer concerns, not SDK.65- **PHP, eBPF auto-instrumentation** — not covered.66- **Coralogix platform internals** (data routing, index policies, APM UI config) — platform topics.6768## Deprecated native SDKs6970Native Coralogix SDKs are EOL **June 30, 2026** — redirect to OTel and do not provide configuration for legacy packages.7172## Upstream references7374Coralogix OTel instrumentation: [Java](https://coralogix.com/docs/opentelemetry/instrumentation-options/java-opentelemetry-instrumentation/) · [Python](https://coralogix.com/docs/opentelemetry/instrumentation-options/python-opentelemetry-instrumentation/) · [Node.js](https://coralogix.com/docs/opentelemetry/instrumentation-options/nodejs-opentelemetry-instrumentation/) · [.NET](https://coralogix.com/docs/opentelemetry/instrumentation-options/dotnet-opentelemetry-instrumentation/) · [Go](https://coralogix.com/docs/opentelemetry/instrumentation-options/golang-opentelemetry-instrumentation/)7576[Coralogix OTel docs](https://coralogix.com/docs/opentelemetry/) · [OpenTelemetry official docs](https://opentelemetry.io/docs/)
coralogix