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.

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/

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. The collector’s ID and any supplied attributes are used to determine which pipelines to include in the configuration. Attributes are key-value pairs. The collector’s attributes, also known as system attributes, are combined with any attribute overrides, also known as custom attributes, to determine the 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 a map 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.

json Copy

--- 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:

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 @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 @get-collector.json \
    -u "user:pass" \
    --header "Content-Type: application/json" \
    -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/GetCollector
{"attributeOverrides":{"mycustomattr":"mynewcustomval"}, "createdAt":"2024-09-02T14:59:13Z", "updatedAt":"2024-09-02T16:18:38Z", "attributes":{"cluster":"dev", "collector.os":"linux", "collector.version":"v1.4.0-devel+wip", "namespace":"team-c"}, "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