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:
CollectorService is the service that is used to register, update, and provide remote configuration for collectors.
Method Name
Request Type
Response Type
Description
GetConfig
GetConfigRequest
GetConfigResponse
Returns the collector’s configuration
RegisterCollector
RegisterCollectorRequest
RegisterCollectorResponse
Registers the collector with the given ID and attributes and updates the collector’s attributes if the collector is already registered and the attributes are different
GetCollector
GetCollectorRequest
Collector
Returns information about the collector
ListCollectors
ListCollectorsRequest
Collectors
Returns information about all collectors
CreateCollector
CreateCollectorRequest
Collector
Creates a new collector
UpdateCollector
UpdateCollectorRequest
Collector
Updates an existing collector
BulkUpdateCollectors
BulkUpdateCollectorsRequest
BulkUpdateCollectorsResponse
Updates multiple collectors
DeleteCollector
DeleteCollectorRequest
DeleteCollectorResponse
Deletes an existing collector
BulkDeleteCollectors
BulkDeleteCollectorRequest
BulkDeleteCollectorResponse
Deletes multiple collectors
ListCollectorAttributes
ListCollectorAttributesRequest
ListCollectorAttributesResponse
Returns all attributes that are used for all 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.
Field
Type
Label
Description
id
list(string)
required
IDs of collectors to delete
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.
Field
Type
Label
Description
ids
list(string)
required
ID of the Collector to update
ops
list(Operation)
required
Operations applied to collectors in the order they are provided
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.
Field
Type
Label
Description
id
string
required
ID of the collector
attribute_overrides
map(string)
optional
Attribute overrides for the collector
created_at
google.protobuf.Timestamp
optional
Timestamp that the collector was created
updated_at
google.protobuf.Timestamp
optional
Timestamp that the collector was last updated
name
string
optional
Name of the collector used for display purposes only
attributes
map(string)
optional
Last set of attributes received from the collector in a RegisterCollectorRequest
enabled
bool
optional
Whether the collector is enabled or not
Collectors
Collectors represents a list of collectors.
Field
Type
Label
Description
collectors
list(Collector)
List of collectors
CreateCollectorRequest
CreateCollectorRequest is the request to create a new collector.
Field
Type
Label
Description
collector
Collector
New collector
DeleteCollectorRequest
DeleteCollectorRequest is the request to delete an existing collector.
Field
Type
Label
Description
id
string
required
ID of the collector to delete
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.
Field
Type
Label
Description
id
string
required
ID of the collector to retrieve
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.
Field
Type
Label
Description
id
string
required
ID of the collector the configuration is for
attributes
map(string)
optional
System attributes of the collector
hash
string
optional
Determines if the configuration has changed
GetConfigResponse
GetConfigResponse is the server-to-collector response message that contains the collector’s configuration.
Field
Type
Label
Description
content
string
Full configuration for the collector
hash
string
Determines if the configuration has changed and avoids sending the full configuration if it has not changed
not_modified
bool
Set to true if the configuration has not changed, indicating the client should not update its 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.
Field
Type
Label
Description
attributes
map(string)
System attributes for all collectors
attribute_overrides
map(string)
Attribute overrides for all collectors
ListCollectorAttributesResponse.AttributesEntry
Field
Type
key
string
value
Attributes
Attributes
Field
Type
Label
Description
values
list(Value)
All values for a single attribute
Value
Field
Type
Label
Description
value
string
Single value for an attribute
ListCollectorsRequest
ListCollectorsRequest is the request to list collectors according to any specified matchers.
If no matchers are specified, all collectors are returned.
Field
Type
Label
Description
matchers
list(string)
Matchers used to filter the list of collectors
Operation
Operation is a single operation to apply to a collector’s attribute overrides.
Field
Type
Label
Description
op
Operation.OpType
required
Operation to perform
path
string
required
Path for the operation formatted as a JSON path
from
string
optional
Used by the move and copy operations to specify the source path to move or copy the value from
value
string
optional
Value for add and replace operations, as well as selective removal
oldValue
string
optional
Old value to match against for a selective replace
Operation.OpType
Value
Description
ADD
Adds a new attribute or replaces one with the specified path
REMOVE
Removes the attribute at the specified path
REPLACE
Replaces the existing value of the attribute at the specified path but does not create one if none exists
MOVE
Moves the attribute with the specified from to the specified path
COPY
Copies the attribute at the specified from to the specified path
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.
Field
Type
Label
Description
id
string
required
ID of the collector
attributes
map(string)
optional
Attributes of the collector to register
name
string
optional
Name of the collector
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.
Field
Type
Label
Description
collector
Collector
Collector to be updated
Examples
The following JSON files contain sample payloads about a collector, karasu.