Documentation Grafana Cloud Observe and act Optimize data 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.

The endpoint returns a JSON array of recommendations:

JSON Copy

[
  {
    "tokens": ["level=info ts=", "<*>", " caller=", "<*>", " msg=\"request completed\" status=200 duration=", "<*>"],
    "locked": false,
    "configured_drop_rate": 0,
    "volume": 1288490188,
    "ingested_lines": 4500000,
    "queried_lines": 1200,
    "recommended_drop_rate": 80,
    "superseded": false,
    "levels": ["info"],
    "segments": {}
  }
]

In the preceding example:

• tokens contains the detected pattern. Concatenate the values in order to rebuild the pattern text.
• volume is the estimated ingested volume in bytes over the lookback window.
• ingested_lines is the estimated number of ingested lines that match the pattern.
• queried_lines is the number of matching lines returned by queries.
• configured_drop_rate is the percentage of matching lines currently dropped.
• recommended_drop_rate is the percentage that Adaptive Logs recommends dropping.

The API doesn’t return query-frequency labels or projected savings. Derive query frequency from queried_lines and ingested_lines.

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",
     "active_interval": "1h"
   }

Create a permanent 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.

Create a temporary exemption

Set active_interval in exemption.json, then use the temporary exemption endpoint:

Bash Copy

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

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

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.