Troubleshooting: symptom → root cause

Maps recurring user symptoms to the actual root cause and the first action to take. Most issues come down to pipeline placement, exporter config, or an upstream connectivity/IAM problem masquerading as a config issue.

Contents

• Operating rule: confirm this is a collector problem
• Symptom to root-cause table
• Debugging workflow
• Collector self-telemetry metrics
• Debug exporter isolation
• High-signal collector logs
• Scope checks and key facts

Operating rule: is the problem even the OTel Collector?

Before editing pipelines, confirm the symptom actually belongs to the collector. "No data reaching Coralogix" is often a DNS / TLS / proxy / domain / API-key problem — not a pipeline problem. If the user has added a transform processor to "force data through" and it made no difference, the root cause is upstream. Say so clearly before continuing.

Symptom → Root cause table

Debugging workflow

If you see "it's broken," work through this order before editing pipelines:

1. Enable the collector's self-telemetry

If the collector isn't already emitting its own metrics, turn it on temporarily:

service:
  telemetry:
    metrics:
      level: detailed
      readers:
        - periodic:
            interval: 30000
            exporter:
              otlp:
                protocol: grpc
                endpoint: "http://localhost:4317"
    logs:
      level: info

Metrics to read first:

2. Add a debug exporter, mirror the problematic signal

exporters:
  debug:
    verbosity: detailed
    sampling_initial: 5
    sampling_thereafter: 200

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [coralogix, debug]    # mirror

If debug sees the data but coralogix doesn't, the problem is the exporter / connectivity. If neither sees it, the problem is upstream (receiver, source app, network).

Only turn verbosity: detailed on in production for short diagnostic windows — it is expensive, especially on Windows.

3. Read the collector logs

Typical high-signal log lines:

• Exporting failed. Dropping data. + rpc error: code = X — exporter connectivity / auth / quota. Cross-check against domain, private_key, egress.
• INVALID_ARGUMENT — OTTL problem in transform/filter. Switch to the OTTL skill.
• can't get K8s Instance Metadata; node name is empty — resourcedetection/resource_catalog on wrong collector type (see table above).
• cannot start pipelines: failed to start "X" processor — processor on the wrong collector role, or missing env/RBAC.
• denied by autogke-no-write-mode-hostpath — GKE Autopilot Warden, see setup-kubernetes.md.

4. Cross-check quickly that it isn't the skill's own scope

• OTTL issues → OTTL skill.
• Fleet Management config precedence → preset-fleet-management.md.
• Memory / page cache → ops-memory-performance.md.

5. Only now, touch the pipeline

When you do edit pipelines, change one thing at a time and watch the self-telemetry. Batching two changes in a single apply wastes the diagnostic budget.

Key Facts

• Most "no data" problems are connectivity, not pipeline. Check domain/key/egress first.
• coralogix domain field is a bare hostname. Not a URL, not endpoint:.
• Enable self-telemetry before editing anything. otelcol_* metrics are the highest-signal diagnostic.
• Mirror suspect signals through a debug exporter to isolate where data drops.
• single-writer violations cause duplicate metrics and partial resets. Deduplicate resource attributes across collectors.
• If memory_limiter fires chronically, look upstream — cardinality/volume — before sizing up the collector.
• APM missing errors = spanmetrics placement. Move to agent, upstream of sampling.
• Incomplete cross-service traces = tail_sampling placement + loadbalancing routing. Central gateway, consistent_hashing by trace_id.