Documentation Grafana Cloud Adaptive Telemetry Adaptive Logs Manage as code Adaptive Logs API

Adaptive Logs HTTP API

The following topic describes the Adaptive Logs HTTP API.

Before you begin

To interact with the API, gather the following information:

• URL: In the form https://<your-grafana-cloud-loki-url>.grafana.net. To find your URL value, go to your Grafana Cloud account and check the Details page of your hosted Loki endpoint.
• TENANT: The numeric instance ID where you want to use Adaptive Logs. To find your TENANT value, go to your Grafana Cloud account and check the Details page of your hosted Loki endpoint for Username / Instance ID.
• TOKEN: A token from a Grafana Cloud Access Policy that has the adaptive-logs:admin scope for your stack. More details about available permissions and scopes can be found in RBAC for Adaptive Logs.

Patterns and recommendations

Adaptive Logs groups your log lines into patterns and generates recommendations for each pattern based on query usage over a rolling 15-day window. Each pattern has a drop rate that controls what percentage of matching log lines are dropped upon ingestion.

A recommendation looks similar to this:

JSON Copy

{
  "pattern": "level=info ts=<_> caller=<_> msg=\"request completed\" status=200 duration=<_>",
  "volume": "1.2 GiB",
  "query_frequency": "rarely",
  "current_drop_rate": 0,
  "recommended_drop_rate": 80,
  "projected_savings": "960 MiB"
}

In the preceding example:

• pattern is the detected log line pattern with variable portions replaced by placeholders.
• volume is the total ingested volume for this pattern over the past 15 days.
• query_frequency indicates how often this pattern is queried. Possible values are never, rarely, sometimes, often, and always.
• current_drop_rate is the percentage of log lines currently being dropped (0 to 100).
• recommended_drop_rate is the percentage that Adaptive Logs recommends dropping.
• projected_savings is the estimated savings based on the recommended rate.

List recommendations

Download recommendations for patterns and drop rates using the following command. TOKEN and TENANT are variables defined in the requirements section.

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/recommendations"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

Exemptions

Exemptions allow you to prevent certain logs from being dropped, even if Adaptive Logs recommends dropping them. Exemptions are defined using LogQL stream selectors. You can also create temporary exemptions that expire after a set duration.

The exemption format looks like this:

Below are examples of exemptions:

1. Exempt all logs from the login service from being dropped.

   JSON Copy

   {
     "stream_selector": "{service_name=\"login\"}"
   }

2. Exempt all logs from the payments namespace with a reason.

   JSON Copy

   {
     "stream_selector": "{namespace=\"payments\"}",
     "reason": "Required for PCI compliance audit trail"
   }

3. Create a temporary exemption that expires after one hour.

   JSON Copy

   {
     "stream_selector": "{service_name=\"api-gateway\"}",
     "reason": "Investigating latency spike",
     "expires_at": "2025-04-21T15:00:00Z"
   }

Create an exemption

Bash Copy

curl -u "$TENANT:$TOKEN" --request POST --data @exemption.json "$URL/adaptive-logs/exemptions"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

If successful, the server returns a JSON object including the id of the newly created exemption.

List exemptions

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/exemptions"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

Get an exemption

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/exemptions/<exemption_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The exemption_id is the identifier of the exemption to fetch, as returned by the server when creating the exemption.

Update an exemption

Bash Copy

curl -u "$TENANT:$TOKEN" --request PUT --data @exemption.json "$URL/adaptive-logs/exemptions/<exemption_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The exemption_id is the identifier of the exemption to update, as returned by the server when creating the exemption.

Delete an exemption

Bash Copy

curl -u "$TENANT:$TOKEN" --request DELETE "$URL/adaptive-logs/exemptions/<exemption_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The exemption_id is the identifier of the exemption to delete, as returned by the server when creating the exemption.

Drop rules

Drop rules let you define custom rules that drop a percentage of log lines matching specific criteria. Unlike recommendations, which are system-generated, drop rules are user-defined and give you fine-grained control over which logs are dropped.

Each drop rule has the following format:

The body object has the following fields:

Below is an example of a drop rule:

JSON Copy

{
  "segment_id": "__global__",
  "name": "Drop noisy health checks",
  "version": 1,
  "disabled": false,
  "body": {
    "stream_selector": "{service_name=\"api-gateway\"}",
    "drop_rate": 90,
    "levels": ["info", "debug"],
    "log_line_contains": ["healthcheck"]
  }
}

Create a drop rule

Bash Copy

curl -u "$TENANT:$TOKEN" --request POST --data @drop-rule.json "$URL/adaptive-logs/drop-rules"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

If successful, the server returns a JSON object including the id of the newly created drop rule.

List drop rules

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/drop-rules"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

You can filter results with the following query parameters:

Get a drop rule

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/drop-rules/<drop_rule_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The drop_rule_id is the identifier of the drop rule to fetch, as returned by the server when creating the drop rule.

Update a drop rule

Bash Copy

curl -u "$TENANT:$TOKEN" --request PUT --data @drop-rule.json "$URL/adaptive-logs/drop-rules/<drop_rule_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The drop_rule_id is the identifier of the drop rule to update, as returned by the server when creating the drop rule.

Delete a drop rule

Bash Copy

curl -u "$TENANT:$TOKEN" --request DELETE "$URL/adaptive-logs/drop-rules/<drop_rule_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The drop_rule_id is the identifier of the drop rule to delete, as returned by the server when creating the drop rule.

Segments

Segments let you organize log streams into groups based on a shared label, so you can manage Adaptive Logs recommendations on a per-team or per-service basis.

Each segment has the following format:

Below is an example of a segment:

JSON Copy

{
  "name": "Billing team",
  "selector": "{team=\"billing\"}"
}

Create a segment

Bash Copy

curl -u "$TENANT:$TOKEN" --request POST --data @segment.json "$URL/adaptive-logs/segment"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

If successful, the server returns a JSON object including the id of the newly created segment.

List segments

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/segments"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

Get a segment

Bash Copy

curl -u "$TENANT:$TOKEN" "$URL/adaptive-logs/segment?segment=<segment_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The segment_id is the identifier of the segment to fetch, as returned by the server when creating the segment.

Update a segment

Bash Copy

curl -u "$TENANT:$TOKEN" --request PUT --data @segment.json "$URL/adaptive-logs/segment?segment=<segment_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The segment_id is the identifier of the segment to update, as returned by the server when creating the segment.

Delete a segment

Bash Copy

curl -u "$TENANT:$TOKEN" --request DELETE "$URL/adaptive-logs/segment?segment=<segment_id>"

TOKEN must belong to an access policy with the adaptive-logs:admin scope.

The segment_id is the identifier of the segment to delete, as returned by the server when creating the segment.