Log Streaming (REST API)

This article walks you through configuring log streaming via REST API.

All configuration is stored in etcd and served by api-service on port 443 with JWT authentication - the same API endpoint you use for storage management. On each server, lightbox-exporter reads the configuration from etcd and renders a pipeline config that Alloy polls via the remotecfg protocol.

Bash
Copy

Prerequisites

  • A running Lightbits cluster.
  • The system:cluster-admin JWT for the cluster.

Step 1: Setting your JWT and Server

Export the server hostname and your system:cluster-admin JWT, so that all subsequent commands can reference them:

Bash
Copy

All curl commands below use $SERVER and $JWT.

Step 2: (Optional) Creating a TLS Bundle

A TLS bundle holds the certificate material used for mTLS connections to an Rsyslog target. Skip this step if you only need a Loki target.

Bash
Copy

List the bundles to verify:

Bash
Copy

Step 3: Creating Sources

A source tells Alloy which log stream to collect on each server. You can collect from journald (by syslog identifier) or from a file path.

Control-plane Services (journald)

Bash
Copy

Data-plane Services (journald)

Bash
Copy

Event Log Files (Optional)

Event logs are written to files only when emit_service_events_to_file is enabled in the Ansible config.

Bash
Copy

List all sources to verify:

Bash
Copy

Expected output (abbreviated):

JSON
Copy

Step 4: Creating Targets

A target is a log destination. You can have multiple targets; every collected log line is forwarded to all enabled targets.

Loki Target (No TLS)

Bash
Copy

Rsyslog Target (mTLS, Requires TLS Bundle from Step 2)

Bash
Copy

List the targets to verify:

Bash
Copy

Expected output:

JSON
Copy

Step 5: Verifying Collector Status

Once the configuration is applied, Alloy polls lightbox-exporter for the rendered pipeline config (via the remotecfg protocol) and begins shipping logs. Use the collectors API to check that each server's Alloy agent is healthy:

Bash
Copy

Expected output when everything is healthy:

JSON
Copy

If pipelineHealth is DEGRADED or ERROR, check failingExporters for which targets are unreachable.

Modifying the Configuration

Sources and targets can be updated or deleted without restarting any service. Alloy picks up the new pipeline config on its next remotecfg poll (default: 1 minute).

Bash
Copy

Inspecting the Rendered Alloy Pipeline Config

You can inspect the pipeline config that lightbox-exporter renders for Alloy by querying the remotecfg endpoint on the server directly (no auth required — node-local only):

Bash
Copy
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Common Administration Tasks

© 2026 Lightbits Labs™

On This Page
Log Streaming (REST API)PrerequisitesStep 1: Setting your JWT and ServerStep 2: (Optional) Creating a TLS BundleStep 3: Creating SourcesStep 4: Creating TargetsStep 5: Verifying Collector StatusModifying the ConfigurationInspecting the Rendered Alloy Pipeline ConfigControl-plane Services (journald)Data-plane Services (journald)Event Log Files (Optional)Loki Target (No TLS)Rsyslog Target (mTLS, Requires TLS Bundle from Step 2)