Graylog Collector
Graylog Collector is a log shipper that reads logs from a host and sends them to Graylog. You configure it from the Graylog interface, so a host needs no local configuration after its collector is enrolled. This article explains how Graylog Collector connects to Graylog and the concepts you need to know before you deploy and manage collectors.
Hint: Graylog Collector and Graylog Sidecar are separate features that do not share configuration, enrollment, or management. Graylog Sidecar manages third-party log collectors such as Filebeat and NXLog that you install alongside it, while Graylog Collector collects and sends log data on its own.
What Graylog Collector Does
Graylog Collector has two jobs on each host. The first job is collecting log data and sending it to Graylog. The second job is reporting on itself so you can see how every collector is doing without logging into a single host.
You define what a collector reads by adding collector sources in the Graylog interface, and the server delivers that configuration to every collector that needs it. A source can read from files, the systemd journal, the Windows Event Log, or the macOS unified logging system.
Alongside that data, each collector reports its health, host metadata, and the configuration it has applied. It sends its own diagnostic logs to Graylog too, so a failing collector can be diagnosed from the Graylog interface.
How Graylog Collector Connects to Graylog
Each collector maintains two separate connections to Graylog, both over HTTPS. The control channel uses the Open Agent Management Protocol (OpAMP), and the data channel uses the OpenTelemetry Protocol (OTLP).
|
Connection |
Purpose |
Destination |
|---|---|---|
|
Control channel |
Configuration, certificates, and health reporting |
The Graylog server URL given during enrollment |
|
Data channel |
The collected log data |
The ingest endpoint configured in System > Collectors > Settings |
The two connections usually go to different addresses and ports. The control channel goes to the Graylog server. The data channel goes to wherever the collector ingest input is reachable, which is typically a load balancer or the Graylog server itself. Every collector host must be able to reach both.
All communication uses managed private-key infrastructure and is authenticated with certificates.
Graylog handles messages from Graylog Collector the same way it handles messages from any other input. After the messages arrive, they pass through the message processors you have configured (System > Configurations > Message Processors), which include Illuminate for normalization and enrichment, the Pipeline Processor for your own pipeline rules, and the rest of the processing chain. No collector-specific setup is needed, so your existing streams, pipelines, and Illuminate content apply to collector data as they do to everything else.
Fleets, Sources, and Instances
Graylog Collector organizes collectors into fleets. A fleet is a group of collectors that share one configuration, and that configuration is a set of collector sources defining what to collect.
|
Concept |
Description |
|---|---|
|
Instance |
A single running collector, identified by an |
|
Fleet |
One or more instances that share a configuration, typically organized by environment, team, or purpose. A fleet owns its sources. |
|
Source |
A definition of what to collect, made up of a type, a name, and type-specific options such as file paths or journald priority. A source belongs to one fleet and cannot be shared between fleets. |
|
Enrollment token |
A signed token scoped to a single fleet. A collector presents the token once, during enrollment, to obtain the client certificate it uses from then on, so it keeps working after the token expires. Any collector enrolling with a given token joins that token's fleet. |
Plan fleets around what hosts should collect rather than where they are. Hosts that need the same sources belong in the same fleet regardless of location. For example, web servers in three data centers that all collect the same nginx logs belong in one fleet rather than one fleet per data center.
When you add or change a source, Graylog compiles the fleet's sources into a collector configuration and pushes it to every enrolled instance in the fleet over the control channel. Each instance applies the configuration and reports the result back. No restart is required. Instances that have not confirmed applying the current configuration are flagged in the instance list.
A fleet can mix operating systems. Graylog builds each instance's configuration against the operating system that instance reported and omits any source whose type the host does not support. For example, a fleet holding a journald source, a Windows Event Log source, and a file source delivers the journald and file sources to its Linux hosts, and the event log and file sources to its Windows hosts.
Collector Status and Health
Graylog tracks a collector's status and its health separately. Status reflects whether the collector is reporting in, measured against the offline threshold you set in Configure Collector Settings.
|
Status |
Meaning |
|---|---|
|
Online |
The collector reported within the offline threshold. |
|
Offline |
The collector has not reported within the offline threshold. |
The offline status means the collector has stopped reporting. The status does not distinguish between a stopped service, a powered-off host, and a broken network path.
Health is reported by the collector itself. An unhealthy instance reports the error that made it unhealthy and when the state last changed. An instance can be online and unhealthy at the same time because the collector is still reporting while part of its configuration is failing.
An online, healthy collector is not proof that log data is arriving. The control channel and the data channel are separate connections to different addresses, so a collector can be fully managed while its data goes nowhere. See Monitor Collectors for how to confirm that messages are reaching Graylog.
Further Reading
Explore the following additional resources and recommended readings to expand your knowledge on related topics:
