Note
Fleet Management is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. For bug reports or questions, fill out our feedback form.
The Collector HTTP API
The Grafana Fleet Management Collector API offers straightforward CRUD operations on individual collectors as well as bulk deletes and updates.
For a full definition of the Collector API, refer to the .proto
file.
Base URL
You can find the base URL for the Collector API in the Grafana Cloud Fleet Management interface.
- In your Grafana Cloud stack, click Connections > Collector > Fleet Management in the left-side menu.
- On the Fleet Management interface, switch to the API tab.
- Find the URL in the Base URL section.
It looks like the following URL, where
<CLUSTER_NAME>
is the production cluster of your stack:
https://fleet-management-<CLUSTER_NAME>.grafana.net/collector.v1.CollectorService/
CollectorService
CollectorService
is the service that is used to register, update, and provide remote configuration for collectors.
Endpoints
BulkDeleteCollectorsRequest
BulkDeleteCollectorsRequest
is a request to delete multiple collectors.
If any collectors do not exist, the request fails and no collectors are deleted.
BulkDeleteCollectorsResponse
BulkDeleteCollectorsResponse
is the response to a BulkDeleteCollectorsRequest
.
This message is empty and the results of the delete are defined by the HTTP status code of the response.
BulkUpdateCollectorsRequest
BulkUpdateCollectorsRequest
is a request to update multiple Collectors’ attribute_overrides in a single request.
The update is applied in a single transaction, so any errors cause the entire request to fail and no Collectors are updated.
A BulkUpdateCollectorsRequest can be used to add, remove, replace, move, or copy attribute overrides for the specified Collectors.
BulkUpdateCollectorsResponse
BulkUpdateCollectorsResponse
is the response to a BulkUpdateCollectorsRequest
.
This message is empty and the results of the update are defined by the HTTP status code of the response.
Collector
Collector
represents the data for a single Alloy collector.
The ID is used to uniquely identify the collector, and the attributes and attribute_overrides are used to determine which pipelines to include in the collector’s configuration.
Attribute overrides are also known as custom attributes.
These take precedence over attributes set in the collector’s local configuration except for any attributes prefixed with collector.
.
collector.*
attributes are reserved for use by the Fleet Management service.
Collectors
Collectors
represents a list of collectors.
CreateCollectorRequest
CreateCollectorRequest
is the request to create a new collector.
DeleteCollectorRequest
DeleteCollectorRequest
is the request to delete an existing collector.
DeleteCollectorResponse
DeleteCollectorResponse
is the response to a DeleteCollectorRequest
.
This message is empty and the results of the delete are defined by the HTTP status code of the response.
GetCollectorRequest
GetCollectorRequest
is the request to retrieve a collector’s information.
Its response is a Collector
message.
GetConfigRequest
GetConfigRequest
is the request message to get a collector’s configuration.
Attributes are key-value pairs.
The attributes
supplied in the request are combined with custom attributes stored remotely to determine which pipelines are included in the collector’s final configuration.
GetConfigResponse
GetConfigResponse
is the server-to-collector response message that contains the collector’s configuration.
ListCollectorAttributesRequest
ListCollectorAttributesRequest
is the request to list all attributes that are used for all collectors.
ListCollectorAttributesResponse
ListCollectorAttributesResponse
is the response to a ListCollectorAttributesRequest
.
It contains maps of all attributes and all their values that are used for all collectors.
ListCollectorAttributesResponse.AttributesEntry
Attributes
Value
ListCollectorsRequest
ListCollectorsRequest
is the request to list collectors according to any specified matchers.
If no matchers are specified, all collectors are returned.
Operation
Operation
is a single operation to apply to a collector’s attribute overrides.
Operation.OpType
RegisterCollectorRequest
RegisterCollectorRequest
is used to register a collector with the Fleet Management service, or update the collector’s attributes if the collector is already registered.
This request is intended only to be used by the collector itself.
It is sent on startup or when the collector’s local configuration changes.
RegisterCollectorResponse
The response to a RegisterCollectorRequest
.
This message is empty and the results of the registration are defined by the HTTP status code of the response.
UpdateCollectorRequest
UpdateCollectorRequest
is the request to update an existing collector.
It updates the collector with the exact values provided in the request.
Updates are not selective, and any fields that are not provided are removed.
For example, if the enabled
field is not provided, enabled
is treated as false
.
Examples
The following JSON files contain sample payloads about a collector, karasu
.
--- create-collector.json ---
{
"collector": {
"id": "karasu",
"attribute_overrides": {"mycustomattr": "mycustomval"},
"name": "raven",
"enabled": true
}
}
--- update-collector.json ---
{
"collector": {
"id": "karasu",
"attribute_overrides": {"mycustomattr": "mynewcustomval"},
"enabled": true
}
}
--- get-collector.json ---
{
"id": "karasu"
}
--- delete-collector.json ---
{
"id": "karasu"
}
You can use these payloads to make the following requests: