coralogix OpenTelemetry Semantic Conventions for Coralogix
Map Coralogix product behavior to the resource/span/metric/log attributes
it consumes. This top-level file routes to focused references and gives the
cross-product triage workflow; detailed product rules live in references/.
Reference Map and Scope
| Use case | What to do |
|---|---|
| Pick attributes for a new HTTP / DB / RPC / messaging span | apm-service-catalog.md — what each Coralogix APM feature reads; for stable/current/new HTTP metrics use http.request.method |
| Diagnose a missing operation in APM Service Catalog | apm-service-catalog.md — service.name + span kind + operation-name attribute checklist |
| Diagnose a missing database in Database Monitoring | database-monitoring.md — target span attributes are db.system, db.name, db.operation, db.statement, net.peer.name; newer names are bridge inputs |
Handle new DB semantic-convention names such as db.system.name / db.query.text |
database-monitoring.md and spanmetrics.md — DB bridge: db.name first, then server.address, network.peer.name, net.peer.name, network.peer.address, final db.system; include db_calls_total vs calls_total / db_namespace symptoms |
| Diagnose recurring cross-product gotchas | high-signal-rules.md — common scope, topology, cardinality, and product-path rules |
| Answer a specific "which fields / exact names" question | Always read final-answer-checklists.md first — short-answer anchors that must not be inferred or paraphrased away |
| Triage a new OTel semantic-convention breaking change after an SDK / Collector upgrade | triage-workflow.md — classify attribute-name, attribute-value, metric data-point, scope, or topology changes before choosing a bridge |
| Configure Span Metrics labels or cardinality | spanmetrics.md — minimum labels include span_name, service_name, span_kind, status_code, collector_instance_id, http_method, host_name, k8s_cluster_name, cgx.transaction, cgx.transaction.root, db_namespace, db_operation_name, db_collection_name, db_system, application_name, cx_subsystem_name; use k8s.pod.name only for collision cases, not blanket defaults |
| Diagnose Span Metrics writer identity or topology | spanmetrics.md and associated-boundaries.md — restore service.instance.id for resource-key collisions; for gateways name traceID / trace ID load balancing |
Diagnose otel.metric.overflow="true" / otel_metric_overflow="true" series |
spanmetrics.md — expected overflow fallback, not a bug; raw OTLP vs PromQL labels; reduce source cardinality; qualify aggregation_cardinality_limit: 0 vs Helm v0.0.203+ 100,000 default |
| Diagnose missing pods / hosts in Infrastructure Explorer | infrastructure-explorer.md — resource-scope k8s.cluster.name, k8s.namespace.name, k8s.pod.name, k8s.node.name, k8s.container.name, service.name, plus owner k8s.deployment.name / k8s.statefulset.name / k8s.daemonset.name / k8s.job.name / k8s.cronjob.name / k8s.replicaset.name; EC2 tag target is host.name |
| Diagnose resource metadata lifetime / Resource Catalog inventory issues | infrastructure-explorer.md — resource_ttl, interval, otel.entity.interval, schema_url, coralogix/resource_catalog, x-coralogix-ingress: metadata-as-otlp-logs/v1 |
| Diagnose AI Center missing LLM rows | ai-center-genai.md — legacy/new gen_ai.* detection attributes and trace/archive requirements |
Diagnose custom metric temporality, duplicate labels, or _1_total names |
custom-metrics.md — delta temporality, writer identity, Prometheus normalization, and low-cardinality labels |
| Diagnose Lambda/log metadata scope or EC2 tag enrichment | logs-serverless.md — log-record vs resource scope, cx_metadata.*, dashboard/correlation warning, and host identity enrichment |
| Decide when semconv should hand off to another skill | associated-boundaries.md — core owns cx.application.name / cx.subsystem.name; Javaagent setup including OTEL_RESOURCE_ATTRIBUTES and JMX receiver belongs to instrumentation; exact set(...) / where / context belongs to opentelemetry-ottl |
| Decide whether an attribute belongs on resource, span, or metric | Attribute placement below |
Attribute placement
Scope mismatches are a common reason Coralogix features stay empty while telemetry is flowing.
| Level | Use for | Examples |
|---|---|---|
| Resource | producer identity / environment | service.name, service.instance.id, deployment.environment.name, host.name, k8s.pod.name, cloud.region |
| Span | per-operation context | http.route, db.system, db.operation, db.statement, net.peer.name, rpc.method |
| Metric data point | bounded dimensions | http.request.method, http.response.status_code, db.system, generated labels such as span_kind |
| Log record | per-log-event fields | parsed body fields, filelog parser output, request IDs |
| Span event | point-in-time span details | exception.type, exception.message, exception.stacktrace |
Exporter application_name_attributes and subsystem_name_attributes read
resource attributes only; for exact routing answers read
final-answer-checklists.md.
Common Triage Flow
Use this flow when a Coralogix surface is empty or changed after an OTel SDK / instrumentation / Collector upgrade.
- Identify the changed OTel version, instrumentation source, and
schema_urlwhen present. - Identify the affected Coralogix surface and load the matching reference above.
- Inspect raw telemetry before and after transforms with the collector
debugexporter. - Classify the break as one of:
- attribute-name rename;
- attribute-value / enum rename;
- generated metric label or data-point change;
- resource/span/metric/log-record scope mismatch;
- collection topology or product-path gap.
- Choose the bridge location conceptually:
- span attributes before APM / DB / Span Metrics consume spans;
- generated RED metric labels after
spanmetrics; - resource attributes before export / Resource Catalog correlation;
- GenAI span attributes before trace export plus the AI Center trace path;
- log/resource metadata before exporter routing or serverless metadata processing.
- Hand exact implementation to the owning skill:
opentelemetry-ottlfor transform syntax,opentelemetry-collectorfor pipeline/Helm/Fleet wiring,opentelemetry-instrumentationfor SDK and sampler setup, andcorefor Coralogix app/subsystem routing.
Minimal evidence-only collector config for step 3:
receivers:
otlp:
protocols:
grpc: {}
http: {}
exporters:
debug:
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
exporters: [debug]
metrics:
receivers: [otlp]
exporters: [debug]
logs:
receivers: [otlp]
exporters: [debug]
Use this only to inspect raw scopes and attribute names; production pipeline
wiring still belongs to opentelemetry-collector.
For worked diagnosis examples, read triage-workflow.md.
Limitations
This skill diagnoses telemetry semantics. Hand off implementation details:
core:cx.application.name,cx.subsystem.name, regional domains, and application/subsystem routing order.opentelemetry-instrumentation: SDK env vars, sampler chains,CoralogixTransactionSampler, GenAI proxy/library setup, and manual span code.opentelemetry-ottl: exactset(...),replace_pattern(...), contexts, and where clauses.opentelemetry-collector: collector pipeline wiring, Helm/Fleet values, rendered ConfigMaps, exporter queues, Resource Catalog paths, and profile pipeline setup.- Product workflows: dashboard queries, SLOs, alerts, synthetics, RUM, and product-specific rule repair unless the root cause is one of the telemetry attribute shapes documented here.