Graylog Sidecar
Graylog Sidecar is a lightweight management service that you install on each host for the central control and monitoring of log collector processes, including Filebeat, Winlogbeat, and Auditbeat. Sidecar eliminates the need to configure and maintain collectors on each server by allowing you to define reusable, centrally managed configurations in the Graylog interface. These configurations can be deployed across many hosts using tags, ensuring consistent behavior and reducing administrative overhead.
This article introduces the core building blocks of Graylog Sidecar, including agents, tags, collector configurations, collectors, and API tokens, and explains how each component works together to deliver reliable log collection. You will learn how the Sidecar architecture operates, how agents authenticate with Graylog, how tags and configurations drive automated deployment, and which operational practices help keep your Sidecar-managed environment healthy and predictable.
Sidecar Architecture
The Graylog node acts as a centralized hub containing log collector configurations. Each Sidecar daemon running on a host periodically fetches all relevant configurations for that host using the Graylog REST API. On its first run, or whenever a configuration change is detected, Sidecar generates backend configuration files locally and restarts only the affected collectors with the updated settings. Collector configurations are centrally managed through the Graylog web interface.
Graylog Sidecar can run as a Windows service or a Linux daemon on supported, message-producing devices such as servers, network appliances, or application hosts. In most deployments, Sidecar runs on every system that writes logs you want to collect centrally.
Sidecar Agent
The Sidecar agent is a lightweight service installed on each host. It communicates with the Graylog REST API to fetch assigned configurations, applies them locally, and manages the collector processes. The agent can start, stop, or restart collectors, handle failures, and report operational status. Each agent sends regular heartbeat messages and collector health data back to Graylog so you can monitor deployments centrally.
Example
A Linux host web-server-01 runs a Sidecar agent. The agent authenticates with its API token, matches the tags ["production","webservers"], pulls the Filebeat configuration assigned to those tags, and starts Filebeat to ship NGINX logs to Graylog for indexing and search.
Tags, Collector Configurations, and Collectors
Tags are labels you assign in sidecar.yml to segment machines by environment, role, operating system, or location.
Collector configurations are templates you create in Graylog that describe inputs (log sources), processors (filters or enrichments), and outputs (destinations) for a collector.
Collectors are the actual binaries (Filebeat, Winlogbeat, Auditbeat, etc.) that Sidecar manages on each host. On Linux, Sidecar includes binaries for Filebeat and Auditbeat. On Windows, Sidecar includes binaries for Filebeat and Winlogbeat. Sidecar can also work with any existing collector on your endpoints (e.g. Sysmon, NXLog, Packetbeat). An agent automatically retrieves and applies any configuration that shares at least one tag with its own tag list.
Example
A configuration tagged for ["production","webservers"] defines Filebeat to read /var/log/nginx/*.log and send to a Graylog Beats input on your-graylog-server:5044. Any agent with either tag receives and applies that configuration when it checks in.
API Token, Node ID/Name, and Communication
Each Sidecar agent uses an API token to authenticate to the Graylog REST API. The agent identifies itself with a unique node_id and human-readable node_name, which appear in the Graylog interface under System > Sidecars for management and search. Note that node_name resolves to the endpoint hostname or container name by default. Agents poll the API based on the update_interval setting in sidecar.yml, which is set to 10 seconds by default, to fetch configuration changes and report heartbeats. Adjusting this value changes how frequently Sidecar checks in with Graylog and applies new configurations.
Example
Create a token named production-servers in the Graylog interface. On web-server-01, set tags, server_url (HTTPS), and the token in /etc/graylog/sidecar/sidecar.yml. (node_id and node_name are automatically generated and do not require manual setting.)The agent registers, appears in the interface, and begins managing the collector.
Forwarder vs. Sidecar
The Graylog Forwarder and Graylog Sidecar serve different roles within a Graylog environment. The Forwarder focuses on collecting logs from remote sources and securely transmitting them to your Graylog Server. It uses input profiles to determine which inputs to start, and it sends all gathered log data directly to the Forwarder input configured on the Graylog Server.
The Graylog Sidecar, by contrast, manages external log collectors such as Filebeat, Winlogbeat, or Auditbeat. It is installed directly on each log source and acts as a lightweight control agent. Sidecar regularly retrieves its configuration from Graylog and applies those settings to the underlying log collector, ensuring consistent and centrally managed log collection behavior.
Further Reading
Explore the following additional resources and recommended readings to expand your knowledge on related topics:
