This metering agent simplifies usage metering of applications and can be used as part of a usage-based billing strategy. It performs the following functions:
- Accepts usage reports from a local source, such as an application processing requests
- Aggregates that usage and persists it across restarts
- Forwards usage to one or more endpoints, retrying in the case of failures
git clone https://github.com/GoogleCloudPlatform/ubbagent.git
cd ubbagent
make setup deps build
bin/ubbagent --help
The BUILD.bazel files can be regenerated with:
bazel run //:gazelle
To update WORKSPACE go_repository rules from a go.mod file:
bazel run //:gazelle -- update-repos -from_file=go.mod
To build, test and run with bazel:
bazel build ...
bazel test ...
bazel run ubbagent
# The identity section contains authentication information used by the agent.
identities:
- name: gcp
gcp:
# A base64-encoded service account key used to report usage to
# Google Service Control.
encodedServiceAccountKey: [base64-encoded key]
# The metrics section defines the metric names and types that the agent
# is configured to record.
metrics:
- name: requests
type: int
# The endpoints section of a metric defines which endpoints the metric data is sent to.
endpoints:
- name: on_disk
- name: servicecontrol
# The aggregation section indicates that reports that the agent receives for this metric should
# be aggregated for a specified period of time prior to being sent to the reporting endpoint.
aggregation:
bufferSeconds: 60
- name: instance-seconds
type: int
# The empty passthrough second indicates that no aggregation should occur for this metric.
# Reports received are immediately sent to the reporting endpoint.
passthrough: {}
endpoints:
- name: on_disk
- name: servicecontrol
# The endpoints section defines where metering data is ultimately sent. Currently
# supported endpoints include:
# * disk - some directory on the local filesystem
# * servicecontrol - Google Service Control: https://cloud.google.com/service-control/overview
endpoints:
- name: on_disk
disk:
reportDir: /var/ubbagent/reports
expireSeconds: 3600
- name: servicecontrol
servicecontrol:
identity: gcp
serviceName: some-service-name.myapi.com
consumerId: project:<project_id>
# The sources section lists metric data sources run by the agent itself. The currently-supported
# source is 'heartbeat', which sends a defined value to a metric at a defined interval.
sources:
- name: instance-seconds
heartbeat:
metric: instance-seconds
intervalSeconds: 60
value:
int64Value: 60
labels:
auto: trueTo run the agent, provide the following:
- A local TCP port (for the agent's HTTP daemon)
- The path to the agent's YAML config file
- The path to a directory used to store state
- Optional logging parameters supported by glog (See
-logtostderrand-vbelow)
ubbagent --config path/to/config.yaml --state-dir path/to/state \
--local-port 3456 -logtostderr -v 2
The agent provides a local HTTP instance for interaction with metered software.
An example curl command to post a report:
curl -X POST -d "{\"name\": \"requests\", \"startTime\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\", \"endTime\": \"$(date -u +"%Y-%m-%dT%H:%M:%SZ")\", \"value\": { \"int64Value\": 10 }, \"labels\": { \"foo\": \"bar2\" } }" 'http://localhost:3456/report'
The agent also provides status indicating its ability to send data to endpoints.
curl http://localhost:3456/status
{
"lastReportSuccess": "2017-10-04T10:06:15.820953439-07:00",
"currentFailureCount": 0,
"totalFailureCount": 0
}
See DESIGN.md.
The easiest way to deploy the metering agent into a Kubernetes cluster is as a sidecar container alongside the software being metered. A Dockerfile is provided that builds such a container. It accepts the following parameters as environment variables:
AGENT_CONFIG_FILE- Required. The path to a file containing the agent's configuration.AGENT_STATE_DIR- Optional. The path under which the agent stores state. If this parameter is not specified, no state will be stored.AGENT_LOCAL_PORT- Optional. The pod-local port on which the agent's HTTP API will listen for reports and provide status. If this parameter is not specified, the agent will not start its HTTP server.
The configuration file is run through envsubst, so it can contain any additional parameters as well. For example, a service account key and a servicecontrol consumerId may be stored in a Kubernetes secret and passed in as environment variables.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent