Documentation Grafana Cloud Instrument and send data Fleet Management Reference Collector HTTP API

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.

Find the base URL

You can find the base URL for the Collector API in the Grafana Cloud Fleet Management interface.

1. In your Grafana Cloud stack, click Connections > Collector > Fleet Management in the left-side menu.
2. On the Fleet Management interface, switch to the API tab.
3. Find the URL in the Base URL section. It looks like the following URL, where <CLUSTER_NAME> is the production cluster of your stack:

Copy

https://fleet-management-<CLUSTER_NAME>.grafana.net/collector.v1.CollectorService/

Rate limits

Requests to the Collector API are limited based on the endpoint called.

• Calls to the RegisterCollector and GetConfig endpoints are limited to 20 requests per second.
• Calls to the GetConfig endpoint that originate in the Fleet Management application (for example, if you view a collector’s remote configuration in the UI) are limited to 3 requests per second.
• Calls to all other endpoints are limited to 3 requests per second.

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’ remote attributes 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 remote attributes 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 local_attributes and remote_attributes are used to determine which pipelines to include in the collector’s configuration. Remote attributes were previously known as attribute overrides. 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 local_attributes supplied in the request are combined with remote attributes stored in Fleet Management 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.

RemoteConfigStatus

RemoteConfigStatuses

EffectiveConfig

Represents the complete configuration that governs the collector’s current behavior, which may differ from the last remote configuration if the collector is using a local configuration instead or in addition.

AgentConfigMap

AgentConfigFile

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.

The virtual attribute collector.ID is returned with an empty value as long as a single collector exists.

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 remote attributes.

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.

JSON Copy

--- create-collector.json ---
{
    "collector": {
        "id": "karasu",
        "remote_attributes": {"myremoteattr": "myremoteval"},
        "name": "raven",
        "enabled": true
    }
}

--- update-collector.json ---
{
    "collector": {
        "id": "karasu",
        "remote_attributes": {"myremoteattr": "mynewremoteval"},
        "enabled": true
    }
}

--- get-collector.json ---
{
    "id": "karasu"
}


--- delete-collector.json ---
{
    "id": "karasu"
}

You can use these payloads to make the following requests:

shell Copy

$ curl -q \
    -d @create-collector.json \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/CreateCollector
{}%

$ curl -q \
    -d @update-collector.json \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/UpdateCollector
{}%

$ curl -q \
    -d @get-collector.json \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/GetCollector
{"id":"karasu","remoteAttributes":{"myremoteattr":"mynewremoteval"},"createdAt":"2024-09-02T14:59:13Z","updatedAt":"2024-09-02T16:18:38Z","enabled":true}%

$ curl -q \
    -d @delete-collector.json \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/DeleteCollector
{}%

$ curl -q \
    -d '{}' \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/ListCollectors
{}%

$ curl -q \
    -d '{"matchers": ["collector.os=linux"]}' \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/ListCollectors
{}%