Skip to main content

Collectors

A Lumetry Collector runs close to the systems it observes and sends telemetry to Lumetry over outbound HTTPS. It is useful when direct collection by the Lumetry service is not appropriate or when the monitored host must continue collecting during a network outage.

What a collector does​

The current collector can:

  • collect basic Linux host CPU, memory-use, and one-minute load metrics;
  • buffer collected points locally when Lumetry cannot be reached;
  • upload buffered points through the standard metric-ingestion API;
  • report liveness, version, queue depth, dropped-point count, and clock skew;
  • receive versioned collection configuration;
  • rotate its own credential when requested.
  • poll assigned metric sources with bounded, fair execution;
  • run interactive source tests without blocking scheduled collection;
  • deliver internal webhook notifications without exposing an inbound connection to the zone.

The collector uses the same metric contract as any other ingestion client. Collector data therefore enters the normal catalog, rule-evaluation, alert, and incident flows.

Network model​

Collectors initiate all communication toward Lumetry. Lumetry does not need an inbound connection to the customer network. Host agents in the same customer zone can initiate connections to the collector's relay endpoint.

customer host                         Lumetry
    collect metrics
    buffer locally
         |
         +---- outbound HTTPS -----> enroll / heartbeat / config / metrics

When host agents are deployed, the collector can relay their enrollment, heartbeat, and metric requests while preserving each agent's identity. Agents can fall back to a direct Lumetry connection when the collector is unavailable and network policy allows it.

Use TLS for every production connection. A collector credential is a dedicated machine credential: it is not a user access token and cannot call general user-management APIs.

Polling and internal delivery are capability-gated. Work claims carry a lease, execution budget, and single-use claim token. Results are accepted only from the current owner; stale results are rejected instead of overwriting newer work.

Enrollment​

Enrollment separates installation from identity:

  1. An administrator creates a collector registration in Lumetry.
  2. Lumetry returns a one-time enrollment token. The token is shown only in that response and has an expiry time.
  3. The collector sends the token and basic host facts to the enrollment endpoint.
  4. Lumetry returns the collector ID and its ongoing machine credential.
  5. The collector persists that identity and uses it for future requests.

A generic installer or container image contains no customer identity. The one-time token is what binds an installation to its Lumetry workspace.

If a pending registration's token expires, an administrator can generate a replacement. Once a collector has enrolled, it cannot use the enrollment-token endpoint again.

Offline behavior​

Collection and upload are separate activities. If the network or Lumetry endpoint is temporarily unavailable, collection continues and points remain in a bounded local buffer. Uploads resume from the oldest queued data after connectivity returns.

The default buffer limit is 500 MB. When the configured limit is exceeded, the oldest queued points are removed first. Queue depth and cumulative dropped-point count are reported in heartbeats and visible to operators.

Collector last-seen values are shown as elapsed ages, such as 12 minutes ago, so operators can scan liveness without comparing exact timestamps.

This is an at-least-once delivery model: a point can be retried after an interrupted upload. Downstream evaluation is designed to avoid duplicate operational outcomes.

Configuration​

Collector configuration is a versioned JSON document. The collector:

  1. checks whether a newer revision is available;
  2. fetches the document when needed;
  3. validates it before applying it;
  4. acknowledges the revision as applied or rejected;
  5. keeps the last valid configuration if a new revision is invalid.

The current host-metric configuration is:

{
  "hostMetrics": {
    "enabled": true,
    "intervalSeconds": 60
  }
}

intervalSeconds must be between 10 and 3600. Unknown properties are ignored so newer configuration documents do not break older collectors.

Health and lifecycle​

Collector status is one of:

StatusMeaning
pendingRegistered but not yet enrolled.
activeEnrolled and allowed to communicate.
duplicate_suspectedHeartbeats suggest the same credential may be running in more than one process.
revokedAll credentials are invalid and the collector can no longer upload.

Lumetry also surfaces missed heartbeats, significant clock skew, and suspected credential duplication as system alerts. A temporary offline period does not automatically revoke the collector.

Revocation is final for that collector identity. Enroll a replacement rather than trying to reactivate a revoked identity.