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

The Fleet Management Collector API is available at the following base URL:

Copy

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

<CLUSTER_NAME> is the production cluster where your stack is located.

To find your production cluster, access your Grafana Cloud stack and navigate to Connections > Collector > Configure.

Follow the on-screen instructions to begin an Alloy installation. You don’t need to install Alloy, but you do want to view the installation and set up commands provided by the template. Look for the value of the GCLOUD_FM_URL variable to find your <CLUSTER_NAME>. This is an example of the variable:

GCLOUD_FM_URL="https://fleet-management-prod-001.grafana.net"

In this example, prod-001 is your <CLUSTER_NAME>.

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