Buildkite Agent Metrics
Note: Formerly known as
buildkite-metrics, but now
buildkite-agent-metrics to reflect the focus of the tool.
Either download the latest binary from Github Releases or install with:
go get github.com/buildkite/buildkite-agent-metrics
Several running modes are supported. All of them require an Agent Registration Token, found on the Buildkite Agents page.
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-agent-metrics -token abc123 -interval 30s
Restrict it to a single queue with
-queue if you're scaling a single cluster of agents:
buildkite-agent-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, it requires a
go1.x environment and respects the following env vars:
aws lambda create-function \ --function-name buildkite-agent-metrics \ --memory 128 \ --role arn:aws:iam::account-id:role/execution_role \ --runtime go1.x \ --zip-file fileb://handler.zip \ --handler handler
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.
The Cloudwatch backend supports the following arguments:
-cloudwatch-dimensions: A optional custom dimension in the form of
The StatsD backend supports the following arguments:
-statsd-host HOST: The StatsD host and port (defaults to
-statsd-tags: Some StatsD servers like the agent provided by Datadog support tags. If specified, metrics will be tagged by
queueotherwise metrics will include the queue name in the metric. Only enable this option if you know your StatsD server supports tags.
The Prometheus backend supports the following arguments
-prometheus-addr: The local address to listen on (defaults to
-prometheus-path: The path under
prometheus-addrto expose metrics on (defaults to
Upgrading from v2 to v3
-orgargument is no longer needed
-tokenargument is now an Agent Registration Token — the same used in the Buildkite Agent configuration file, and found on the Buildkite Agents page.
- Build and pipeline metrics have been removed, focusing on agents and jobs by queue for auto–scaling. If you have a compelling reason to gather build or pipeline metrics please continue to use the previous version or open an issue with details.
This tool is built with Go 1.11+ and Go Modules.
You can build and run the binary tool locally with golang installed:
export GO111MODULE=on go run *.go -token [buildkite agent registration token]
Currently this will publish metrics to Cloudwatch under the custom metric prefix of
Buildkite, using AWS credentials from your environment. The machine will require the
cloudwatch:PutMetricData IAM permission.
The following metrics are gathered when no specific queue is supplied:
Buildkite > RunningJobsCount Buildkite > ScheduledJobsCount Buildkite > UnfinishedJobsCount Buildkite > IdleAgentsCount Buildkite > BusyAgentsCount Buildkite > TotalAgentsCount Buildkite > (Queue) > RunningJobsCount Buildkite > (Queue) > ScheduledJobsCount Buildkite > (Queue) > UnfinishedJobsCount Buildkite > (Queue) > IdleAgentsCount Buildkite > (Queue) > BusyAgentsCount Buildkite > (Queue) > TotalAgentsCount
When a queue is specified, only that queue's metrics are published.
See LICENSE.md (MIT)