Skip to content

Latest commit

 

History

History
225 lines (188 loc) · 7.81 KB

README.md

File metadata and controls

225 lines (188 loc) · 7.81 KB
Raw

Install Guide

Contents

  1. Installation
  2. Running Stanza
  3. Configuration
  4. Next Steps

Installation

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

Linux/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

Kubernetes

For Kubernetes, there are several guides to install and configure Stanza found here.

Manual Installation

Alternately, feel free to download the latest release directly.

Linux

  1. Downlaod Stanza from the releases page
VERSION=v1.5.0
curl -L -o stanza "https://github.com/observIQ/stanza/releases/download/${VERSION}/stanza_linux_amd64"
  1. Configure file permissions
chmod +x stanza
sudo chown root:root stanza
  1. Configure install directory
sudo mkdir -p /opt/observiq/stanza
sudo mv stanza /opt/observiq/stanza/stanza
  1. Create Systemd service file with the following content
sudo vim /etc/systemd/system/stanza.service
[Unit]
Description=Stanza Log Agent
After=network.target
StartLimitIntervalSec=120
StartLimitBurst=5
[Service]
Type=simple
PIDFile=/tmp/log-agent.pid
User=root
Group=root
Environment=PATH=/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
WorkingDirectory=/opt/observiq/stanza
ExecStart=/opt/observiq/stanza/stanza --log_file /opt/observiq/stanza/stanza.log --database /opt/observiq/stanza/stanza.db
SuccessExitStatus=143
TimeoutSec=120
StandardOutput=null
Restart=on-failure
RestartSec=5s
[Install]
WantedBy=multi-user.target
  1. Bootstrap config file
sudo vim /opt/observiq/stanza/config.yaml
pipeline:
- type: file_input
  include:
  - /var/log/messages
- type: stdout
  1. Reload Systemd, Enable Stanza, Start Stanza
sudo systemctl daemon-reload
sudo systemctl enable stanza
sudo systemctl start stanza
  1. Install plugins (optional)
curl -L -o stanza-plugins.tar.gz https://github.com/observIQ/stanza/releases/download/v1.5.0/stanza-plugins.tar.gz
sudo tar -xf stanza-plugins.tar.gz -C /opt/observiq/stanza

Questions:

  1. Why does Stanza run as root? Running as root gives Stanza the ability to listen on privileged network ports and read any log file on the system. Using a non root user is supported by updating the systemd service.

Local File System Stanza Mirror

For Linux and macOS it is possible to run the script from a local mirror,
passing in the URL. See the Local Mirror documentation.

Running Stanza

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 or check its status, here's how:

Linux

# systemd
systemctl start stanza
systemctl stop stanza
systemctl status stanza

# sysv
service stanza start
service stanza stop
service stanza status

macOS

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

Windows

Start-Service -Name "stanza"
Stop-Service -Name "stanza"
Get-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_level       The log level of the agent logger (default: INFO)
--log_file        The location of the agent log file. If not specified, stanza will log to `stdout`
--max_log_size    The maximum size of the agent log file in MB before rotating (default: 10)
--max_log_backups The maximum number of agent log files to retain when rotating (default: 5)
--max_log_age     The maximum number of days to retain a rotated agent log file (default: 7)

Configuration

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 Google Cloud Monitoring. Add in your own credentials and restart the agent to generate another log line. The project_id field is optional as the credentials file will include the project ID by default.

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 Google Cloud.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/operators/google_cloud_output.md
  - type: google_cloud_output
    project_id: sample_project
    credentials_file: /tmp/credentials.json

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 Google Cloud.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/operators/google_cloud_output.md
  - type: google_cloud_output
    project_id: sample_project
    credentials_file: /tmp/credentials.json

Alternatively, you can use a plugin for log monitoring. This config.yaml collects logs from MySQL via a plugin and sends them to Google Cloud. By default, MySQL plugin collects general, slow query, and error logs. More details of the MySQL plugin can be viewed here.

pipeline:
  # An example input that configures a MySQL plugin.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/plugins.md
  - type: mysql
    enable_general_log: true
    general_log_path: "/var/log/mysql/general.log"

  # An example output that sends captured logs to Google Cloud.
  # For more info: https://github.com/observIQ/stanza/blob/master/docs/operators/google_cloud_output.md
  - type: google_cloud_output
    project_id: sample_project
    credentials_file: /tmp/credentials.json

That's it! You should have logs streaming to Google Cloud. 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.

Next Steps

  • Read up on how to write a stanza pipeline.
  • Check out stanza's list of operators.
  • Check out the FAQ.
  • Let us know what you think! Email us, or open a GitHub issue.