Setup Host Metrics with OpenTelemetry

If you run the collector inside Kubernetes, set k8s.cluster.name so SigNoz can group and disambiguate infrastructure entities (pods, nodes, namespaces, and workloads), especially when you monitor more than one cluster. Unlike namespace and workload names (which the k8sattributes processor reads from the Kubernetes API), a cluster has no canonical name of its own, so it must be set explicitly.

Recommended: set it via the env detector (works on every platform, including self-managed and on-prem). Pass the name through OTEL_RESOURCE_ATTRIBUTES and keep env in your detector list:

processors:
  resourcedetection:
    detectors: [env, system]

export OTEL_RESOURCE_ATTRIBUTES="k8s.cluster.name=<your-cluster-name>"

On managed Kubernetes, the cloud detectors can populate it for you:

• GKE: detected automatically; include gcp in your detectors.

• Amazon EKS: disabled by default; enable it explicitly (requires the EC2:DescribeInstances IAM permission):

  config.yaml

  processors:
    resourcedetection:
      detectors: [env, eks, system]
      eks:
        resource_attributes:
          k8s.cluster.name:
            enabled: true

• Azure AKS: disabled by default; enable it the same way:

  config.yaml

  processors:
    resourcedetection:
      detectors: [env, aks, system]
      aks:
        resource_attributes:
          k8s.cluster.name:
            enabled: true

For all detectors and options, see the OpenTelemetry resourcedetection processor documentation, specifically the Environment Variable, Amazon EKS, GCP Metadata, and Azure AKS detector sections.

If you only want host metrics from a Docker host (no container metrics, no log shipping), use this trimmed config:

receivers:
  hostmetrics:
    root_path: /hostfs
    collection_interval: 60s
    scrapers:
      cpu: {}
      disk: {}
      load: {}
      filesystem: {}
      memory: {}
      network: {}
      paging: {}
      process:
        mute_process_name_error: true
        mute_process_exe_error: true
        mute_process_io_error: true
        mute_process_user_error: true
      processes: {}
      system: {}
 
processors:
  batch:
  resourcedetection:
    detectors: [env, system, docker]
 
exporters:
  otlp:
    endpoint: "ingest.<region>.signoz.cloud:443"
    tls:
      insecure: false
    headers:
      "signoz-ingestion-key": "<your-ingestion-key>"
 
service:
  pipelines:
    metrics:
      receivers: [hostmetrics]
      processors: [resourcedetection, batch]
      exporters: [otlp]

Then run:

docker run -d \
  --name otelcol-hostmetrics \
  --volume /:/hostfs:ro \
  --volume $(pwd)/config.yaml:/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:latest \
  --config=/etc/otelcol-contrib/config.yaml

For a fuller collector that also captures container metrics and logs, use the Docker Collection Agent install guide.

Configure Different Frequencies

You can configure different collection intervals for different metrics by defining multiple hostmetrics receivers. This is useful if you want frequently changing metrics (like CPU/Memory) to be collected more often than stable ones (like Filesystem).

receivers:
  # Receiver for high-frequency metrics (e.g., every 10s)
  hostmetrics/fast:
    collection_interval: 10s
    scrapers:
      cpu: {}
      memory: {}
 
  # Receiver for low-frequency metrics (e.g., every 1m)
  hostmetrics/slow:
    collection_interval: 60s
    scrapers:
      filesystem: {}
      disk: {}
      network: {}
 
service:
  pipelines:
    metrics:
      receivers: [hostmetrics/fast, hostmetrics/slow]
      # ... other processors and exporters

No metrics appearing in SigNoz

Symptoms: Host not visible in Infrastructure Monitoring > Hosts tab.

Resolution:

1. Check the collector logs. Refer to the troubleshooting section of your environment's collector guide (VM / Docker / k8s-infra) for the exact command.
2. Verify the hostmetrics receiver is enabled in your config and listed in the metrics pipeline under service > pipelines.
3. Ensure the collector can reach the SigNoz endpoint (port 443 for Cloud, 4317 for Self-Hosted).

Host Name is blank/empty

Symptoms: Host name appears blank or empty in Infrastructure Monitoring > Hosts tab.

Cause: Metrics are missing the host.name resource attribute (metadata the collector attaches to every metric to identify which host it came from). This typically happens when:

• The resourcedetection processor is not added to the processors section of your collector config, or
• The processor is defined but not enabled in your metrics pipeline (the processors list under service > pipelines > metrics).

Resolution:

1. Verify that the resourcedetection processor is in your processors section:

processors:
  resourcedetection:
    detectors: [env, system, docker]
  batch:

2. Verify that resourcedetection is listed in your metrics pipeline before batch:

service:
  pipelines:
    metrics:
      receivers: [hostmetrics]
      processors: [resourcedetection, batch]
      exporters: [otlp]

3. Restart the collector to apply changes.

Verification: After restarting, go to Infrastructure Monitoring > Hosts. Your host should now appear with its hostname populated.

Connection Refused

Symptoms: Logs show connection refused errors.

Resolution:

• Ensure the OTLP endpoint is reachable.
• Verify the correct port is being used.
• Check firewall settings.

Invalid Key (Cloud)

Symptoms: HTTP 401 Unauthorized errors in logs.

Resolution:

• Double-check your ingestion key in config.yaml.
• Ensure it matches the key in SigNoz (Settings > Ingestion Settings).