Troubleshooting vLLM monitoring on Kubernetes

Resolve common issues that occur when monitoring vLLM pods on Kubernetes with the Instana OpenTelemetry Collector.

No vLLM metrics in Instana

The OpenTelemetry Collector is not scraping metrics from your vLLM pods, or the metrics are not reaching Instana.

How to troubleshoot

  1. Verify that the vLLM metrics endpoint is reachable: 
    kubectl exec -n <namespace> <vllm-pod-name> -- \
  curl http://localhost:<metrics-port>/metrics
  2. Verify that the namespace, component label, and port values in values.yaml exactly match your pod description.
  3. Verify that the vLLM pod is in the Running phase: 
    kubectl get pods -n <namespace>
  4. Review the collector logs for scrape errors: 
    kubectl logs -n monitoring <otel-collector-pod> | grep -i "vllm\|error\|scrape"

Metrics not reaching Instana

The collector is scraping metrics but failing to export them to Instana due to connectivity, authentication, or TLS configuration issues.

How to troubleshoot

  1. Verify that the OTLP endpoint is reachable from within the cluster.
  2. Verify that the x-instana-key header value is correct.
  3. Review TLS settings. Set insecure: true only for non-production environments.
  4. Review the collector logs for exporter errors: 
    kubectl logs -n monitoring <otel-collector-pod> | grep -i "export\|error"