From d6495dd3f4cd72a6639d6c85b344804ab50b4512 Mon Sep 17 00:00:00 2001 From: Lachlan Donald Date: Fri, 10 Aug 2018 14:59:56 +1000 Subject: [PATCH] Improve docs around how to run --- README.md | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 61ab7ae1..2b5df91b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Buildkite Metrics +# Buildkite Agent Metrics -A command-line tool for collecting [Buildkite](https://buildkite.com/) agent and job statistics for external metrics systems, focusing on enabling auto-scaling. Currently [AWS Cloudwatch](http://aws.amazon.com/cloudwatch/), [StatsD](https://github.com/etsy/statsd) and [Prometheus](https://prometheus.io) are supported. +A command-line tool for collecting [Buildkite](https://buildkite.com/) agent metrics, focusing on enabling auto-scaling. Currently [AWS Cloudwatch](http://aws.amazon.com/cloudwatch/), [StatsD](https://github.com/etsy/statsd) and [Prometheus](https://prometheus.io) are supported. [![Build status](https://badge.buildkite.com/80d04fcde3a306bef44e77aadb1f1ffdc20ebb3c8f1f585a60.svg)](https://buildkite.com/buildkite/buildkite-metrics) @@ -14,18 +14,36 @@ go get github.com/buildkite/buildkite-metrics ## Running -Run the metrics agent using an Agent Registration Token, found on the [Buildkite Agents page](https://buildkite.com/organizations/-/agents): +Several running modes are supported. All of them require an Agent Registration Token, found on the [Buildkite Agents page](https://buildkite.com/organizations/-/agents). + +### Running as a Daemon + +The simplest deployment is to run as a long-running daemon that collects metrics across all queues in an organization. ``` -buildkite-metrics -token abc123... +buildkite-metrics -token abc123 -interval 30s ``` -By default this will publish metrics for every queue with connected agents and unfinished jobs, and a total of all metrics. Restrict it to a single queue with `-queue` if you're scaling a single cluster of agents: +Restrict it to a single queue with `-queue` if you're scaling a single cluster of agents: ``` -buildkite-metrics -token abc123... -queue my-queue +buildkite-metrics -token abc123 -interval 30s -queue my-queue ``` +### Running as an AWS Lambda + +An AWS Lambda bundle is created and published as part of the build process. + +It's entrypoint is `handler.handle`, it requires a `python2.7` environment and respects the following env vars: + + - BUILDKITE_TOKEN + - BUILDKITE_BACKEND + - BUILDKITE_QUEUE + - BUILDKITE_QUIET + - BUILDKITE_CLOUDWATCH_DIMENSIONS + +Take a look at https://github.com/buildkite/elastic-ci-stack-for-aws/blob/master/templates/metrics.yml for examples of usage. + ### Backends By default metrics will be submitted to CloudWatch but the backend can be switched to StatsD or Prometheus using the command-line argument `-backend statsd` or `-backend prometheus` respectively. @@ -44,7 +62,7 @@ The Prometheus backend supports the following arguments * `-prometheus-addr`: The local address to listen on (defaults to `:8080`). * `-prometheus-path`: The path under `prometheus-addr` to expose metrics on (defaults to `/metrics`). -### Upgrading from v2 +### Upgrading from v2 to v3 1. The `-org` argument is no longer needed 2. The `-token` argument is now an _Agent Registration Token_ — the same used in the Buildkite Agent configuration file, and found on the [Buildkite Agents page](https://buildkite.com/organizations/-/agents). @@ -83,20 +101,6 @@ Buildkite > (Queue) > TotalAgentsCount When a queue is specified, only that queue's metrics are published. -## AWS Lambda - -An AWS Lambda bundle is created and published as part of the build process. - -It's entrypoint is `handler.handle`, it requires a `python2.7` environment and respects the following env vars: - - - BUILDKITE_TOKEN - - BUILDKITE_BACKEND - - BUILDKITE_QUEUE - - BUILDKITE_QUIET - - BUILDKITE_CLOUDWATCH_DIMENSIONS - -Take a look at https://github.com/buildkite/elastic-ci-stack-for-aws/blob/master/templates/metrics.yml for examples of usage. - ## License See [LICENSE.md](LICENSE.md) (MIT)