Billing event tracking (Ruby)
Track billable usage events from the GitLab Rails monolith with Gitlab::BillingEvents::Client. The client sends Snowplow structured events with a billable_usage context to the Data Insights Platform billing collector.
Events go to the production billing collector, except for GitLab.com staging, GitLab QA instances,
and instances whose CUSTOMER_PORTAL_URL points at the staging Customers Portal.
Those use the staging billing collector, so their usage reaches the same CustomersDot
environment as their subscription.
The client has two entry points. Use track_billing_event for a tally and
track_billing_snapshot for a point-in-time reading. See
Counters and snapshots.
On an air-gapped instance the same calls store usage locally instead of emitting it. See Air-gapped instances.
For the schema field reference, see Billable events schema.
Track a billing event
To trigger a billing event, call the Gitlab::BillingEvents::Client.track_billing_event method with the desired arguments:
Gitlab::BillingEvents::Client.track_billing_event(
event_type: 'secrets_read',
category: self.class.name,
unit_of_measure: 'request',
quantity: 1,
namespace: namespace,
user: current_user,
idempotency_key: "secrets_read:#{unique_request_id}",
metadata: {
mount_path: '/secrets/group-123',
audit_request_id: 'abc123'
}
)Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
event_type | Yes | Billable event name, for example secrets_read. | |
category | Yes | Originating class or module. Use self.class.name. | |
unit_of_measure | Yes | Billing unit: request, secret, tokens, bytes, or similar. | |
quantity | Yes | Usage amount. Must be a positive number. | |
namespace | Yes | Namespace record. Sets namespace_id and root_namespace_id. | |
project | No | nil | Project record. Sets project_id. |
user | No | nil | User record. Sets subject, subject_type, and global_user_id. |
idempotency_key | No | nil | String used for generating event_id. The downstream billing collector deduplicates events based on event_id, so the supplied value needs to be unique for each event that should be billed. When absent, a random UUID is generated on every track_billing_event call. |
timestamp | No | Time.current | Time of the billable activity. Defaults to now. Pass a specific time for an event to represent a different reporting window. |
metadata | No | nil | Hash with product-specific context, stored as a JSON object in the event payload. Set feature_qualified_name for any event that should be billed: CustomersDot treats an event without one as unbillable. |
Emitted payload example
The following is an example of the billable_usage context the client produces. The payload follows the billable events schema:
{
"event_id": "a1b2c3d4-5678-5aaa-bbbb-ccccddddeeee",
"event_type": "secrets_read",
"unit_of_measure": "request",
"quantity": 1,
"timestamp": "2026-06-22T14:30:00Z",
"namespace_id": 9870,
"root_namespace_id": 9870,
"project_id": null,
"subject": "12345",
"subject_type": "User",
"global_user_id": "gid:abc123def456",
"realm": "SaaS",
"deployment_type": ".com",
"instance_id": "b8e45d3c-57f8-4a6f-b106-511801fd1155",
"unique_instance_id": "6680b88f-8a28-5d0b-8387-4c8d4e07d1bd",
"instance_version": "19.2.0",
"host_name": "gitlab.com",
"correlation_id": "c15c2216ec4d0679bccead19f5e1e9d0",
"metadata": {
"mount_path": "/secrets/group-123",
"audit_request_id": "abc123"
}
}Instance identifiers
instance_idis the instance UUID (Gitlab::CurrentSettings.uuid).unique_instance_idis the identifier CustomersDot uses to resolve the event to a subscription or trial. On GitLab.com it isGitlab::GlobalAnonymousId.instance_uuid. On GitLab Self-Managed and GitLab Dedicated it is thegitlab_instance_uidclaim of the instance’s Cloud Connector token, which CustomersDot issued for the instance. When no token is available, the client falls back toGitlab::GlobalAnonymousId.instance_uuid, and CustomersDot cannot resolve the event.
Counters and snapshots
Two methods take the same arguments and differ only in how repeated calls in a single day are treated:
| Method | Use for | Repeated calls in a day |
|---|---|---|
track_billing_event | Something that happened. A secret was read, a workflow completed. | Accumulate |
track_billing_snapshot | A current total. How many secrets exist, how many artifact versions are retained. | Supersede one another |
Choose based on what the number means, not on how often you send it. A point-in-time
reading sent through track_billing_event is summed, which inflates the total by
counting the same underlying usage more than once.
The distinction only affects air-gapped instances, where usage is folded into a daily row. Both methods emit identically over the network.
Air-gapped instances
An air-gapped instance cannot reach the billing collector, so usage sent over the
network is lost. When such an instance is licensed offline, the client writes to a
local daily aggregate table instead of emitting, and an administrator exports that data
for upload. This is behind the local_billing_persistence feature flag, which is enabled
by default.
Callers do not need to detect this. The same call works on both kinds of instance.
Internal event for correlation
Every call to track_billing_event also fires a usage_billing_event
internal event with:
label: the billingevent_id(UUID), used to join billing and analytics data.property: the billingevent_type(for example,secrets_read).
The client passes the same user, namespace, and project arguments
to the internal event, so Service Ping metrics can aggregate billing
activity by namespace, user, or project.
Add Service Ping metrics for a billing event type
Adding a metric is not required for an implementation, but can help provide more data for analysis.
To create the new metric, use the internal events CLI to generate a metric definition. When prompted:
- Select
usage_billing_eventas the event name. - Add a
filteronpropertywith your billingevent_typevalue (for example,secrets_read). This selects only the billing events for your feature. - Add
uniqueif you need distinct-count metrics (for example, unique namespaces or users).
For details on filters and unique properties, see the internal event metric definition guide.
Alternatively, copy an existing metric definition manually.
For example, copy
ee/config/metrics/counts_all/count_total_usage_billing_event_secrets_read.yml
and update the fields for your feature (such as key_path,
product_group, and the filter property value).
Test locally
Start Snowplow Micro:
gdk start snowplow-microOpen a Rails console and send an event, for example:
ns = Namespace.first Gitlab::BillingEvents::Client.track_billing_event( event_type: 'secrets_read', category: 'TestConsole', unit_of_measure: 'request', quantity: 1, namespace: ns, metadata: { test: true } )Visit the UI dashboard to see the billing events received by Snowplow Micro.