coralogix/opentelemetry-skills
OpenTelemetry Collector deployment, instrumentation (Java/Python/Node.js/.NET/Go), and OTTL pipeline transforms for Coralogix — coralogix exporter config, Helm chart selection, Kubernetes topology, ECS/EKS/GKE deployments, SDK setup, APM transactions, and OTTL cardinality/PII/routing.
92
96%
Does it follow best practices?
Impact
92%
1.10xAverage score across 127 eval scenarios
Advisory
Suggest reviewing before use
custom-metrics.mdskills/opentelemetry/opentelemetry-semantic-conventions/references/
Custom Metrics Semantic Shape
Custom Metrics issues often look like semantic-convention issues even when the source is OTLP metrics data model behavior, generated Prometheus label normalization, or multi-writer aggregation. Use this reference when the customer is emitting application metrics directly rather than span-derived Span Metrics.
Metric identity and label rules
Metric labels should be bounded and stable. Good labels describe a small, known vocabulary that a dashboard needs to slice by. Bad labels carry per-user, per-request, raw URL, UUID, array, or process-instance values.
| Label type | Guidance |
|---|---|
| Business dimensions | Keep low-cardinality values such as status, purpose_code, fetch_type, tenant tier, or region. |
| Service identity | Prefer resource attributes such as service.name; avoid emitting both dotted and normalized copies as independent labels. |
| HTTP grouping | Prefer route-like labels such as endpoint or http.route; avoid full URLs and query strings. |
| Arrays | Emit one datapoint per element plus an aggregate metric instead of serializing arrays into a label. |
| Errors/outcomes | Use a tiny fixed vocabulary such as success / failure or a controlled error_type. |
If a metric has both service.name / service.instance.id and
service_name / service_instance_id, check whether two collection paths
are contributing identity differently. Coralogix and Prometheus-facing
paths normalize dotted labels into underscore labels, so mixed values can
create duplicate series even though the names appear related.
Temporality and normalized names
OTLP Sum metrics have aggregation temporality. Coralogix can receive both
cumulative and delta streams, but support for delta does not remove
single-writer and aggregation requirements.
| Shape | Product-visible effect |
|---|---|
| Cumulative monotonic sum | Coralogix may expose a Prometheus-style name with _1_total appended; query with rate/increase as appropriate. |
| Delta sum from one stable writer | Can be accepted, but query behavior and aggregation must match customer intent. |
| Delta sum from multiple writers with the same labels | Can aggregate incorrectly unless writer identity is preserved or a real metrics aggregation step sums the intended streams before converting or exporting. |
| Gauge for current state | Use for point-in-time values such as queue depth; do not use gauges for event counts. |
When customers see a metric emitted as consent_raised but queried as
consent_raised_1_total, treat this as Coralogix/Prometheus normalization
for a cumulative OTLP sum, not necessarily as a source instrumentation bug.
Multi-writer delta remediation
For delta metrics where multiple clients write the same label set:
- Confirm the actual OTLP temporality with a collector
debugexporter. - Identify which labels define the intended aggregate.
- Decide whether the product should keep writers separate or collapse them:
- To keep writer separation, preserve a stable writer-unique identity such
as
service.instance.id, process identity, host, pod, or another bounded resource key before conversion/export. - To collapse writers into one total, use an actual metrics aggregation
operation that sums datapoints for the intended low-cardinality label
set, such as a collector metric aggregation processor/operation. Do not
treat
groupbyattrsas the aggregation step; it re-associates attributes and resources but does not sum colliding datapoints.
- To keep writer separation, preserve a stable writer-unique identity such
as
- Convert the corrected delta streams to cumulative with
deltatocumulativeonly when the Coralogix/query path expects cumulative behavior.
Collector processor syntax belongs to opentelemetry-collector; exact OTTL
or transform syntax belongs to opentelemetry-ottl.
Dotted versus normalized label troubleshooting
If the same concept appears in dotted and underscore forms:
- Check whether the source application emits OTel resource attributes while Prometheus/Target Allocator adds normalized labels.
- Decide the canonical identity for the metric series.
- Align values before export, or remove the duplicate label source.
- Do not let
service.instance.idcontain random UUIDs if the product wants stable service-level aggregates.
Ownership boundary
This skill owns the telemetry semantics: temporality, label cardinality, identity shape, and whether a metric is a counter/gauge/histogram.
Hand off:
- Processor ordering, metrics aggregation processor/operation YAML, and
deltatocumulativeYAML toopentelemetry-collector. - Dashboard query rewrites to dashboard/query owners.
- SDK metric instrument choice to
opentelemetry-instrumentationwhen code changes are needed.
References
- OpenTelemetry metrics data model: https://opentelemetry.io/docs/specs/otel/metrics/data-model/
- spanmetrics.md for span-derived RED metrics, which are a separate generated-metrics surface.
.claude-plugin
.codex-plugin
.cursor-plugin
evals
scenario-1
scenario-2
scenario-3
scenario-4
scenario-5
scenario-6
scenario-7
scenario-8
scenario-9
scenario-10
scenario-11
scenario-12
scenario-13
scenario-14
scenario-15
scenario-16
scenario-17
scenario-18
scenario-19
scenario-20
scenario-21
scenario-22
scenario-23
scenario-24
scenario-25
scenario-26
scenario-27
scenario-28
scenario-29
scenario-30
scenario-31
scenario-32
scenario-33
scenario-34
scenario-35
scenario-36
scenario-37
scenario-38
scenario-39
scenario-40
scenario-41
scenario-42
scenario-43
scenario-44
scenario-45
scenario-46
scenario-47
scenario-48
scenario-49
scenario-50
scenario-51
scenario-52
scenario-53
scenario-54
scenario-55
scenario-56
scenario-57
scenario-58
scenario-59
scenario-60
scenario-61
scenario-62
scenario-63
scenario-64
scenario-65
scenario-66
scenario-67
scenario-68
scenario-69
scenario-70
scenario-71
scenario-72
scenario-73
scenario-74
scenario-75
scenario-76
scenario-77
scenario-78
scenario-79
scenario-80
scenario-81
scenario-82
scenario-83
scenario-84
scenario-85
scenario-86
scenario-87
scenario-88
scenario-89
scenario-90
scenario-91
scenario-92
scenario-93
scenario-94
scenario-95
scenario-96
scenario-97
scenario-98
scenario-99
scenario-100
scenario-101
scenario-102
scenario-103
scenario-104
scenario-105
scenario-106
scenario-107
scenario-108
scenario-109
scenario-110
scenario-111
scenario-112
scenario-113
scenario-114
scenario-115
scenario-116
scenario-117
scenario-118
scenario-119
scenario-120
scenario-121
scenario-122
scenario-123
scenario-124
scenario-125
scenario-126
scenario-127
skills
opentelemetry
opentelemetry-collector
references
opentelemetry-instrumentation
opentelemetry-ottl