Collector

The Lumen collector runs in your cluster. It tails pod logs, can scrape Kubernetes Events and CPU/memory usage, and POSTs batches to https://lumen-api.orkestia.dev.

The collector chart lives in a private repository. Your Orkestia account team gives you a checkout (or a chart package) and a pinned image. You do not need the repository to be public to install it.

Enable Lumen and mint an ingest key first — Enable Lumen.

What it collects

Skipped namespaces by default: kube-*, lumen-collector, local-path-storage, ingress-nginx, cert-manager, metrics-server.

Payloads are the same JSON as Send data (RawLog / MetricIngest). With metadata enrichment on, project is app.kubernetes.io/name, then app, then the namespace. Optional Kafka publish uses topic lumen.logs (same body as HTTP logs). Metrics are HTTP-only.

Install

You need kubectl, Helm 3, cluster access, the chart, and the image tag you were given.

1. Auth Secret

The Secret value is the full header line:

kubectl create namespace lumen-collector

kubectl -n lumen-collector create secret generic lumen-collector-auth \
  --from-literal=requestHeader='X-Api-Key: lumk_REPLACE_ME'

Rotate by minting a new key in Usage & keys, updating this Secret, restarting the DaemonSet, then revoking the old key.

2. Helm

From the chart directory:

helm upgrade --install lumen-collector ./deploy/helm/lumen-collector \
  --namespace lumen-collector \
  --create-namespace \
  --set clusterName=my-cluster \
  --set environment=production \
  --set rbac.create=true \
  --set image.repository=<registry-you-were-given>/lumen-collector \
  --set image.tag=<pinned-tag> \
  --set sources.podLogs.parser=cri \
  --set sources.podLogs.minLevel=WARNING \
  --set sources.podLogs.metadataEnabled=true \
  --set sink.type=http \
  --set sink.http.endpoint=https://lumen-api.orkestia.dev/api/logs/ingest/batch \
  --set sink.http.metricsEndpoint=https://lumen-api.orkestia.dev/api/metrics/ingest/batch \
  --set sink.http.requestHeaderSecret.name=lumen-collector-auth

Do not put an organization UUID in values. The key selects the org.

3. Optional: events and usage metrics

helm upgrade lumen-collector ./deploy/helm/lumen-collector \
  --namespace lumen-collector \
  --reuse-values \
  --set rbac.create=true \
  --set sources.events.enabled=true \
  --set sources.metrics.enabled=true

Leave metrics off if kubectl get --raw /apis/metrics.k8s.io/v1beta1 fails.

Logs run as DaemonSet lumen-collector-logs (hostPath for files and offsets under /var/lib/lumen-collector). Events run as a Deployment when enabled.

Confirm

kubectl -n lumen-collector rollout status daemonset/lumen-collector-logs --timeout=180s
kubectl -n lumen-collector get pods -o wide
kubectl -n lumen-collector logs daemonset/lumen-collector-logs --since=10m

Then open lumen.orkestia.dev/logs (source=kubernetes) and Metrics for collector.up under project lumen-collector.

Treat the collector as degraded if collector.up is missing for more than a minute, or if collector.pipeline.failed / .dropped is above zero, even when pods are Running.

Settings worth knowing

Prefer the Secret over putting X-Api-Key in Helm values. The log container reads node log files (uid 0, read-only root filesystem).

Troubleshooting

Next