stanza

README

stanza

Stanza is a fast and lightweight log transport and processing agent. It's designed as a modern replacement for Fluentd, Fluent Bit, and Logstash.

How do I install the agent?

We recommend using our single-line installer provided with each release:

Linux

sh -c "$(curl -fsSlL https://github.com/observiq/stanza/releases/latest/download/unix-install.sh)" unix-install.sh

macOS

sh -c "$(curl -fsSlL https://github.com/observiq/stanza/releases/latest/download/unix-install.sh)" unix-install.sh

Windows

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 ; Invoke-Expression ((New-Object net.webclient).DownloadString('https://github.com/observiq/stanza/releases/latest/download/windows-install.ps1')); Log-Agent-Install

How do I run the agent?

If you installed the agent using the single-line installer above, it's already running as a service! If you'd like to start or stop the agent, here's how:

Linux

# systemd
systemctl start stanza
systemctl stop stanza

# sysv
service stanza start
service stanza stop

macOS

launchctl start com.observiq.stanza
launchctl stop com.observiq.stanza

Windows

Start-Service -Name "stanza"
Stop-Service -Name "stanza"

Manual

If you'd like to run the agent manually rather than as a service, you can do that, too!

# Example Command
stanza

# Supported flags:
--config      The location of the agent config file (default: ./config.yaml)
--plugin_dir  The location of the plugins directory (default: ./plugins)
--database    The location of the offsets database file. If this is not specified, offsets will not be maintained across agent restarts
--log_file    The location of the agent log file. If not specified, stanza will log to `stderr`
--debug       Enables debug logging

How do I configure the agent?

A simple configuration file (config.yaml) is included in the installation. By default it doesn't do much, but is an easy way to get started. By default, it generates a single log entry and sends it to STDOUT every time the agent is restarted.

pipeline:
  # An example input that generates a single log entry when Stanza starts up.
  - type: generate_input
    count: 1
    entry:
      record: This is a sample log generated by Stanza
...
  # An example output that sends captured logs to stdout.
  - type: stdout
...

The first step in configuring stanza is to setup your output. The sample configuration provides examples for sending data to the Elastic stack or Google Cloud Monitoring. Uncomment the destination of your choice and add in your own credentials and host. Restart the agent to generate another log line.

...
pipeline:
  # An example input that generates a single log entry when Stanza starts up.
  - type: generate_input
    count: 1
    entry:
      record: This is a sample log generated by Stanza

  # An example output that sends captured logs to elasticsearch.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/operators/elastic_output.md
  - type: elastic_output
    addresses:
      - http://my_node_address:9200
    api_key: my_api_key
...

Once you've confirmed you're able to send a log entry, you'll want to connect stanza to a log file you're interested in monitoring. We've included a sample file_input configuration in the config file to use (stanza also provide options for UDP, TCP, syslog, and other input streams. They're available here).

...
pipeline:
...
  # An example input that monitors the contents of a file.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/operators/file_input.md
  - type: file_input
    include:
       - /sample/file/path
  ...

  # An example output that sends captured logs to elasticsearch.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/operators/elastic_output.md
  - type: elastic_output
    addresses:
      - http://my_node_address:9200
    api_key: my_api_key
...

That's it! You should have logs streaming to Elasticsearch. From here you can explore all the options available within stanza! You can use existing plugins from our plugin repository or build your own custom pipelines.

To learn more about configuration, visit our docs.

How do I contribute?

First, check out our section on getting started with development

Next, take a look at our contribution guidelines in CONTRIBUTING.md

Other questions?

Check out our FAQ, or open an issue with your question. We'd love to hear from you.