Opentelemetry Semantic Conventions

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](references/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](references/apm-service-catalog.md) — service.name + span kind + operation-name attribute checklist | | Diagnose a missing database in Database Monitoring | [database-monitoring.md](references/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](references/database-monitoring.md) and [spanmetrics.md](references/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](references/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](references/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](references/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](references/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](references/spanmetrics.md) and [associated-boundaries.md](references/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](references/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](references/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](references/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](references/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](references/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](references/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](references/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](#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](references/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.

1. Identify the changed OTel version, instrumentation source, and

schema_url when present.

1. Identify the affected Coralogix surface and load the matching reference

above.

1. Inspect raw telemetry before and after transforms with the collector

debug exporter.

1. 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.

1. 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.

1. Hand exact implementation to the owning skill:

opentelemetry-ottl for transform syntax, opentelemetry-collector for pipeline/Helm/Fleet wiring, opentelemetry-instrumentation for SDK and sampler setup, and core for 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](references/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: exact set(...), 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.

Upstream References

• Coralogix: Aligning Coralogix and OTel naming conventions
• OTel attribute registry
• OTel semantic conventions specification
• OTel Telemetry Schemas

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: coralogix
• Source: coralogix/cx-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.