Skip to content

Commit

Permalink
Goverance (#192)
Browse files Browse the repository at this point in the history 
* Add governance, and update maintainers

* Major documentation update

Co-authored-by: Michael Kelly <[email protected]>
  • Loading branch information
@djaglowski @mkelly
djaglowski and mkelly authored Nov 6, 2020
1 parent b1584e4 commit 7d960ed
Show file tree
Hide file tree
Showing 9 changed files with 276 additions and 204 deletions.
5 changes: 0 additions & 5 deletions CODE_OF_CONDUCT.md
View file

This file was deleted.

39 changes: 19 additions & 20 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,38 +7,34 @@ You can view and edit the source code by cloning this repository:
```bash
git clone https://github.com/observiq/stanza.git
```

## Pull Requests

### How to Send Pull Requests
### How to Submit Pull Requests

Everyone is welcome to contribute code to `stanza` via
GitHub pull requests (PRs).
Everyone is welcome to contribute code to `stanza` via GitHub pull requests (PRs).

To create a new PR, fork the project in GitHub and clone the upstream
repo:
To create a new PR, fork the project in GitHub and clone the upstream repo:

```sh
$ go get -d github.com/observiq/stanza
```

This will put the project in `${GOPATH}/src/github.com/observiq/stanza`. You
can alternatively use `git` directly with:
This will put the project in `${GOPATH}/src/github.com/observiq/stanza`. You can alternatively use `git` directly with:

```sh
$ git clone https://github.com/observiq/stanza
```

This would put the project in the `stanza` directory in
current working directory.
This would put the project in the `stanza` directory in current working directory.

Enter the newly created directory and add your fork as a new remote:

```sh
$ git remote add <YOUR_FORK> [email protected]:<YOUR_GITHUB_USERNAME>/opentelemetry-go
```

Check out a new branch, make modifications, run linters and tests, and
push the branch to your fork:
Check out a new branch, make modifications, run linters and tests, and push the branch to your fork:

```sh
$ git checkout -b <YOUR_BRANCH_NAME>
Expand All @@ -51,13 +47,14 @@ $ git push <YOUR_FORK> <YOUR_BRANCH_NAME>

Open a pull request against the main `stanza` repo.


### How to Receive Comments

* If the PR is not ready for review, please put `[WIP]` in the title,
tag it as `work-in-progress`, or mark it as
[`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
* If the PR is not ready for review, please put `[WIP]` in the title, tag it as `work-in-progress`, or mark it as [`draft`](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
* If you're stuck, tag a maintainer and ask a question. We're here to help each other.
* Make sure CI passes.


### How to Get PRs Merged

A PR is considered to be **ready to merge** when:
Expand All @@ -66,14 +63,15 @@ A PR is considered to be **ready to merge** when:
* CI passes.
* Major feedback is resolved.


## Design Choices

Best practices for developing a builtin operator are documented below, but for changes to
the core agent, we are happy to discuss proposals in the issue tracker.
Best practices for developing a builtin operator are documented below, but for changes to the core agent, we are happy to discuss proposals in the issue tracker.


### Builtin Operator Development
### Operator Development

In order to write a builtin operator, follow these three steps:
In order to write an operator, follow these three steps:
1. Build a unique struct that satisfies the [`Operator`](operator/operator.go) interface. This struct will define what your operator does when executed in the pipeline.

```go
Expand Down Expand Up @@ -108,10 +106,11 @@ func init() {
}
```

## Any tips for building operators?

#### Any tips for building operators?
We highly recommend that developers take advantage of [helpers](operator/helper) when building their operators. Helpers are structs that help satisfy common behavior shared across many operators. By embedding these structs, you can skip having to satisfy certain aspects of the `operator` and `config` interfaces.

For example, almost all operators should embed the [BasicOperator](operator/helper/basic_operator.go) helper, as it provides simple functionality for returning an operator id and operator type.
For example, almost all operators should embed the [BasicOperator](operator/helper/operator.go) helper, as it provides simple functionality for returning an operator id and operator type.

```go
// ExampleOperator is a basic operator, with a basic lifecycle, that consumes
Expand Down
44 changes: 44 additions & 0 deletions GOVERNANCE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Governance

The governance model adopted in Stanza is influenced by many CNCF projects.

## Principles

- **Open**: Stanza is an open source community.
- **Welcoming and respectful**: Stanza follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
- **Transparent and accessible**: Work and collaboration should be done in public.
- **Merit**: Ideas and contributions are accepted according to their technical merit and alignment with project objectives, scope, and design principles.

## Project Maintainers

Maintainers are the first and foremost contributors that are committed to the success of Stanza project. Each maintainer should fulfill several of the following responsibilities:

* Strive to make stanza widely while taking care not to unjustifiably inflate its scope.
* Carefully consider input from the community and seek consensus with amongst maintainers.
* Create and classify GitHub issues and perform pull request reviews for other maintainers and the community.
* Use ones best judgement to apply all applicable [labels](https://github.com/observiq/stanza/labels) to each new GitHub issue.
* Make sure that ongoing PRs are moving forward at the right pace or closing them if they are not moving in a productive direction.
* Create releases of the library as necessary.

## Process of becoming a maintainer

* Understand that maintainers are expected to have a deep understanding of the project and that they should be able to independently fulfill maintainer responsibilities.
* Talk to some of the existing [maintainers](MAINTAINERS.md). Explain that you are interested in becoming a maintainer and why you think you are a good fit for the role.
* Contribute increasingly complicated PRs under the guidance of the existing maintainers.
* When a maintainer believes you are ready, he or she may nominate you by creating a PR to add your to the list in [MAINTAINERS.md](MAINTAINERS.md).
* Once the existing maintainers have reached consensus that the nominatee is ready for the role and approved the PR, it will be merged and the new maintainer becomes active.

## Process of removing maintainer status

* If a maintainer is no longer interested or cannot perform the maintainer duties listed above, they should volunteer to be moved to emeritus status.
* In extreme cases a PR may be created to remove a maintainer. This PR must be approved by a 2/3 majority of maintainers to be approved.

## Decision making process

Decisions are made based on consensus between maintainers. Proposals and ideas should be submitted as a github issue or PR.

In general, we prefer that technical issues and maintainer membership are amicably worked out between the persons involved. If a dispute cannot be decided independently, then a third-party maintainer (e.g. a mutual contact with some background on the issue, but not involved in the conflict) to arbitrate and the final decision will be made. Decision making process should be transparent to adhere to the principles of Stanza project.

## Credits

Some contents in this documents have been borrowed from the [OpenYurt](https://github.com/alibaba/openyurt) project.
3 changes: 2 additions & 1 deletion MAINTAINERS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,5 @@ This file lists the maintainers of the Stanza project. The responsibilities of m
| ---- | --------- | ----------- |
| [Mike Kelly](mailto:[email protected]) | [mkelly](https://github.com/mkelly) | observIQ |
| [Dan Jaglowski](mailto:[email protected]) | [djaglowski](https://github.com/djaglowski) | observIQ |
| [Camden Cheek](mailto:[email protected]) | [camdencheek](https://github.com/camdencheek) | observIQ |
| [Camden Cheek](mailto:[email protected]) | [camdencheek](https://github.com/camdencheek) | observIQ |
| [Joseph Howell](mailto:[email protected]) | [jhowellbm](https://github.com/jhowellbm) | observIQ |
152 changes: 26 additions & 126 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,134 +1,34 @@
# 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.
<p align="center"><img src="https://github.com/observIQ/stanza/blob/master/docs/images/logo_small.png?raw=true"></p>

[![<observIQ>](https://circleci.com/gh/observIQ/stanza.svg?style=shield&circle-token=980a514f9dc5a48ac2b8e61a4cdb7555ea5646ca)](https://app.circleci.com/pipelines/github/observIQ/stanza)
[![codecov](https://codecov.io/gh/observIQ/stanza/branch/master/graph/badge.svg)](https://codecov.io/gh/observIQ/stanza)
[![Go Report Card](https://goreportcard.com/badge/github.com/observIQ/stanza)](https://goreportcard.com/report/github.com/observIQ/stanza)

## How do I install the agent?

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

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

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

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

To learn more about configuration, visit our [docs](./docs/README.md).

## How do I contribute?

First, check out our section on [`getting started with development`](./docs/development.md)

Next, take a look at our contribution guidelines in [`CONTRIBUTING.md`](./CONTRIBUTING.md)

# About 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. Stanza can run as a standalone agent on all major operating systems, or it can be embedded directly into any Golang application.


# Quick Start

Want to get started right away? Check out our [Quick Start Guide](./docs/README.md)!


## Community

Stanza is an open source project. If you'd like to contribute, check out our First, take a look at our [contribution guidelines](./CONTRIBUTING.md) and [developer guide](./docs/development.md). We look forward to building with you.


## Roadmap

Stanza uses GitHub [projects](https://github.com/observIQ/stanza/projects) to organize future work. There's a lot to do, and more use cases are identified almost daily. We'll keep it organized and moving forward the best we can, but we're always looking for great ideas and contributions of all sizes.


## Code of Conduct

Stanza follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md). Please report violations of the Code of Conduct to any or all [maintainers](MAINTAINERS.md).


## Other questions?

Expand Down
Loading

0 comments on commit 7d960ed

Please sign in to comment.