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

1. Identify the changed OTel version, instrumentation source, and schema_url when present.
2. Identify the affected Coralogix surface and load the matching reference above.
3. Inspect raw telemetry before and after transforms with the collector debug exporter.
4. 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.
5. 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.
6. 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.

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