# Quick Start Guide

## Installation

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

### Linux
```shell
sh -c "$(curl -fsSlL https://github.com/observiq/stanza/releases/latest/download/unix-install.sh)" unix-install.sh
```
### macOS
```shell
sh -c "$(curl -fsSlL https://github.com/observiq/stanza/releases/latest/download/unix-install.sh)" unix-install.sh
```
### Windows
```pwsh
[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
```

#### Alternately, feel free to download the [latest release](https://github.com/observIQ/stanza/releases) directly.


## 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, here's how:

### Linux
```shell
# systemd
systemctl start stanza
systemctl stop stanza

# sysv
service stanza start
service stanza stop
```
### macOS
```shell
launchctl start com.observiq.stanza
launchctl stop com.observiq.stanza
```
### Windows
```pwsh
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!

```shell
# 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
```


## 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.

```yaml
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.

```yaml
...
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](/docs/operators/README.md)).
```yaml
...
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.


## Next Steps

- Read up on how to write a stanza [pipeline](/docs/pipeline.md).
- Check out stanza's list of [operators](/docs/operators/README.md).
- Check out the [FAQ](/docs/faq.md).
- Let us know what you think! [Email us](mailto:stanza@observiqlabs.com), or open a GitHub issue.