@grepr/cli 1.11.5-c840124 → 1.11.5-dbd05e7

package/build/dist/docs-index/2b88210d-e972-4fa5-846a-c9acbf4577f5.txt

@@ -0,0 +1,30 @@
+# Get the usage of an integration's parsed queries
+
+**GET** `/v1/integrations/{integrationId}/exceptions/usage`
+
+**Operation ID**: `getIntegrationExceptionUsage`
+**Summary**: Get the usage of an integration's parsed queries
+Returns the usage the observability vendor reports for the source of each parsed query, such as when a Datadog dashboard was last viewed and its total views, with whether the last attempt to read it worked. Queries the vendor reported nothing for are absent rather than reported as never viewed.
+
+## Tags
+- Integration Exceptions
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+
+## Responses
+
+### 200
+
+Usage retrieved
+
+- **Content-Type**: `application/json` / `ExceptionUsageResponse`
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration not found.

package/build/dist/docs-index/2d1bc194-04b1-4c78-b129-f788ebebf092.txt

@@ -0,0 +1,15 @@
+# recordLogin
+
+**POST** `/v1/me/login`
+
+**Operation ID**: `recordLogin`
+**Summary**: No summary provided.
+## Tags
+- Users
+## Responses
+
+### default
+
+default response
+
+- **Content-Type**: `application/json` / No schema defined

package/build/dist/docs-index/321cc5d6-5671-43c3-a7b5-a5372cc3be68.txt

@@ -0,0 +1,44 @@
+# Start a vendor estimation run
+
+**POST** `/v1/integrations/{integrationId}/exceptions/vendor-estimation-runs`
+
+**Operation ID**: `createVendorEstimationRun`
+**Summary**: Start a vendor estimation run
+Creates a run over the given scope and window covering every exception the integration has imported. Runs are counted in the background, in short slices shared fairly between organizations.
+
+## Tags
+- Integration Exceptions
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+
+## Request Body
+
+**Content-Type**: `application/json`
+
+**Schema**: `CreateVendorEstimationRunRequest`
+
+## Responses
+
+### 200
+
+Run created
+
+- **Content-Type**: `application/json` / `VendorEstimationRun`
+### 400
+
+Bad Request - The window is inverted, starts or ends in the future, or is too long.
+
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration not found.
+
+### 409
+
+Conflict - The organization already has the most runs allowed in progress.

package/build/dist/docs-index/3296cd87-778e-4eea-913b-1aa6d3367631.txt

@@ -0,0 +1,15 @@
+# ExceptionUsage
+
+Usage the vendor reports for the source of one parsed query
+
+**Type**: `object`
+
+## Properties
+
+- name: lastViewedAt (optional)
+  type: string
+  description: When the source was last viewed. Null means the vendor reports it was never viewed.
+
+- name: totalViews (optional)
+  type: integer
+  description: How many times the source was viewed, as the vendor counts them. Datadog counts views since January 2025 and refreshes the count daily.

package/build/dist/docs-index/38f03404-4c25-4355-a717-a5cebafff4f8.txt

@@ -0,0 +1,37 @@
+# List vendor estimation runs for an integration
+
+**GET** `/v1/integrations/{integrationId}/exceptions/vendor-estimation-runs`
+
+**Operation ID**: `listVendorEstimationRuns`
+**Summary**: List vendor estimation runs for an integration
+Returns the integration's estimation runs newest first, in every state.
+
+## Tags
+- Integration Exceptions
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+- **limit** (optional) - query
+  - Maximum runs to return, 1 to 100
+  - Type: integer
+
+## Responses
+
+### 200
+
+Runs retrieved
+
+- **Content-Type**: `application/json` / array of `VendorEstimationRun`
+### 400
+
+Bad Request - Limit is outside 1 to 100.
+
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration not found.

package/build/dist/docs-index/3c2f3b5d-b30e-467e-9fc8-976c11bbf2e1.txt

@@ -0,0 +1,25 @@
+# List an agent's subscriptions
+
+**GET** `/v1/agents/{id}/subscriptions`
+
+**Operation ID**: `subscriptions`
+**Summary**: List an agent's subscriptions
+Returns the agent's pipeline subscriptions, including when each was paused.
+
+## Tags
+- Agents
+## Parameters
+
+- **id** (required) - path
+  - Type: string
+
+## Responses
+
+### 200
+
+Subscriptions retrieved successfully
+
+- **Content-Type**: `application/json` / array of `AgentPipelineSubscription`
+### 401
+
+Unauthorized

package/build/dist/docs-index/3d3102f4-9d25-4fe4-94a9-8803465c61d6.txt

@@ -0,0 +1,91 @@
+Reduce log volume using Grepr's intelligent pattern detection, clustering, and sampling for cost-effective observability at scale.
+
+# Reduce noise and improve the usability of your logs with the log reducer
+
+Grepr's log reducer uses clustering algorithms and real-time pattern discovery to identify repeated messages in high-volume log streams and aggregate those messages into summarized events. These summarized events reduce the volume of redundant, low-value log events while retaining full context for less common and often higher-value events.
+
+The log reducer is a core step in a Grepr log reduction pipeline, where it runs after log events have been processed by the parsing, filtering, and transformation steps and before they are sent to your configured sinks. By sending summarized events rather than the full set of logs to your observability vendor, Grepr significantly reduces the volume of shipped logs and your observability costs.
+
+Messages that do not match any pattern pass through unmodified. You can also configure *exceptions* for specific messages or patterns that must bypass the reducer and be forwarded unmodified to your observability platform. See [Bypass aggregation of important messages with exceptions](/transforms/reducer/exceptions).
+
+Log reduction pipelines also persist your unaggregated raw logs in a Grepr data lake, ensuring you maintain full access to your log data while dramatically reducing storage and processing costs. The data lake allows you to query and analyze your raw logs, for example, when an incident occurs or alerts are raised that require access to the full set of logs for troubleshooting or debugging. See [The Grepr data lake](/grepr-platform/data-lake).
+
+When you create a log reduction pipeline, a reducer is added with default settings suitable for many log processing flows. When needed, you can change the configuration settings to meet your requirements. You can modify reducer settings in the UI or through the Grepr REST API. To configure the reducer in the UI, see [Configure the log reducer in a Grepr pipeline](/transforms/reducer/configuration). For API documentation, see the [LogReducer API specification](/apis/api-spec#schema/LogReducer).
+
+## How log reduction works
+
+The log reducer divides incoming log events into fixed-duration, tumbling windows and produces summaries separately for each window. The reducer creates the summarized events through a multi-step process, including transformations to:
+
+* Normalize fields to help group values that represent the same entity but might differ slightly in format or content.
+* Structure messages to optimize grouping.
+* Group messages using similarity metrics.
+* Output a configurable number of raw sample messages per pattern before summarizing additional matches.
+* Create and output a concise summary of aggregated messages that match an identified pattern along with a configurable sample of raw messages. The summarized events include metadata that provides important context about the aggregated messages and preserves important fields. See [Summary message metadata](#summary-metadata).
+* Add a tag to all output events to indicate whether the type of message it contains is a sample, summary, passthrough, or exception. See [Message types](#message-types).
+
+If the reducer cannot find a matching pattern for a message, the message passes through unmodified. Reasons that the reducer cannot find a pattern include:
+
+* The clustering process is unable to extract patterns from messages.
+* The selected inputs contain neither message tokens nor attribute structure to group by. See [Choose which fields form a pattern](/transforms/reducer/configuration#structured-configuration).
+* The message matches a configured exception rule that prevents it from being reduced.
+
+To learn more about the transformations the reducer applies to messages and how to modify its default behavior, see [Configure the log reducer in a Grepr pipeline](/transforms/reducer/configuration).
+
+## Example: Summarizing repeated and low-value messages
+
+The following image shows an example of a message that's logged repeatedly but provides little to no value because the service it reports on is intentionally left non-running.
+
+The log reducer identifies the pattern in this message and summarizes it into a single message indicating how many times the original message was logged. The summary also includes other metadata about the pattern and the messages that matched it. Important fields from the original messages are included in the summary. The reducer then outputs this summarized message and a sample of the raw messages.
+
+Viewing the summary message shows the added metadata, such as the number of times the message was logged and the start and end times of the messages that were summarized.
+
+## Summary message metadata \[#summary-metadata]
+
+When the reducer generates a summary message for a pattern, it adds the following metadata fields to the output event that provide important context about the aggregated messages. This metadata allows you to understand the pattern's characteristics and the messages it represents, and to link back to the original raw messages if needed.
+
+| Field | Description |
+| --- | --- |
+| `grepr.patternId` | Unique identifier for the pattern. Use this to find related messages. |
+| `grepr.rawLogsUrl` | A direct link to view all raw messages for this pattern in the Grepr data lake. |
+| `grepr.repeatCount` | The number of input messages included in the summary. This can be useful for metrics and [rewriting queries](/transforms/reducer/exceptions#rewrite-queries). |
+| `grepr.receivedTimestamp` | Milliseconds since the Unix epoch when the summary was emitted by Grepr. |
+| `grepr.firstTimeTimestamp` | Milliseconds since the Unix epoch of the first message in this summary. |
+| `grepr.lastTimeTimestamp` | Milliseconds since the Unix epoch of the last message in this summary. |
+
+## Message types \[#message-types]
+
+After processing, each record is assigned a message type, and the `grepr.messagetype` tag is added to output events with one of the following values:
+
+| Value | Description |
+| --- | --- |
+| `sample` | The message is a sample of the original log messages that matched a specific pattern. Sample messages are sent through unmodified until the deduplication threshold is reached. |
+| `summary` | The message summarizes multiple source log messages that matched a specific pattern. Summary messages are generated at the end of each aggregation window for patterns that have exceeded the deduplication threshold. |
+| `passthrough` | The message did not match any existing patterns and was sent through unmodified. |
+| `exception` | The message matched an exception rule and was sent through unmodified. |
+
+## Next steps
+
+* To modify the reducer's default settings to provide further control over how messages are processed, see [Configure the log reducer in a Grepr pipeline](/transforms/reducer/configuration).
+* If you have important messages that must be forwarded to your observability platform without aggregation, configure *exceptions* to ensure these messages skip the reducer step and are forwarded unchanged. See [Bypass aggregation of important messages with exceptions](/transforms/reducer/exceptions).
+
+## Frequently Asked Questions
+
+### What is log reduction in Grepr?
+
+Log reduction is Grepr's process of identifying patterns in high-volume log streams and aggregating similar messages into concise summaries. This reduces the volume of logs shipped to your observability vendor while preserving access to the underlying raw messages through the Grepr data lake.
+
+### How does Grepr identify log patterns?
+
+The reducer applies a multi-step process to each log message. It normalizes variable values such as timestamps, IDs, and IP addresses, structures the message to optimize grouping, and groups messages into patterns using similarity metrics. For each pattern, the reducer forwards a configurable number of raw sample messages before it summarizes additional matches into a single summary event.
+
+### What does the grepr.messagetype tag indicate?
+
+The grepr.messagetype tag records how a message was processed. The value 'sample' means the message was forwarded before the deduplication threshold was reached, 'summary' means the message is a summary of aggregated messages, 'passthrough' means the message did not match any pattern, and 'exception' means the message matched a configured exception.
+
+### What information does a summary message include?
+
+Each summary message includes grepr.patternId for pattern identification, grepr.repeatCount for the count of input messages aggregated, grepr.firstTimeTimestamp and grepr.lastTimeTimestamp for the first and last message timestamps in the summary, grepr.receivedTimestamp for when the summary was emitted, and grepr.rawLogsUrl for a direct link to the raw messages in the Grepr data lake.
+
+### Why might a message pass through without being aggregated?
+
+A message passes through unmodified when the clustering process can't find a pattern that matches it, when the log message field is empty or null, or when the message matches a configured exception rule that prevents aggregation.

package/build/dist/docs-index/42e2b43c-6bc5-413c-9570-e2c550acc2a1.txt

@@ -0,0 +1,118 @@
+Connect a Grepr AI agent to the pipelines and Grepr Agent integrations whose signals it investigates, and control how many signals reach it.
+
+# Subscribe an agent to signal sources
+
+A *signal* is an event that starts an investigation. A *subscription* connects an agent to a source of signals, so that source's events are investigated automatically rather than only when you start an investigation manually.
+
+A subscription carries no filters or conditions of its own. What an agent investigates is decided by what the source emits, so you narrow an agent's work by changing the source rather than the subscription.
+
+## Signal sources \[#sources]
+
+Signals reach an agent in four ways:
+
+| Signal | Where it comes from | How the agent is chosen |
+| --- | --- | --- |
+| Log pattern | A pipeline reducer detected a log pattern it has not seen before. | By subscription. |
+| Pipeline signal | A SQL output in a pipeline is routed to the agent signal and matched an event. | Named in the pipeline's agent signal sink. |
+| Webhook | A Grepr Agent integration received an event. | By subscription. |
+| Manual | You started the investigation. | You chose the agent. |
+
+The log pattern and webhook signals use subscriptions, which you manage on the agent's **Subscriptions** step. The pipeline signal names its agents in the pipeline itself instead, and is described in [_](#agent-signal-sink).
+
+## Subscribe an agent to a pipeline \[#pipeline-sources]
+
+A pipeline can tell your agents when its reducer detects a log pattern it has not seen before, which is how an agent learns about behavior that is new in your systems rather than behavior you already knew to alert on.
+
+### Step 1: Turn on new-pattern signal emission \[#emit-signals]
+
+A pipeline emits nothing to agents until you turn it on, and Grepr refuses a subscription to a pipeline that has it off. Turning it on changes the pipeline's configuration, so Grepr redeploys the pipeline before signals start flowing. Subscribing and unsubscribing afterwards take effect without a restart. A pipeline needs a log reducer or a pattern matcher to emit these signals at all.
+
+To turn it on, go to the pipeline's reducer configuration, open the advanced settings, and select **Emit new-pattern signals to AI agents**.
+
+To learn more about the reducer, see [_](/transforms/reducer/configuration).
+
+### Step 2: Subscribe the agent \[#subscribe-pipeline]
+
+1. On the agent's page, go to the **Subscriptions** step.
+2. In the **Subscribe to a signal source** menu, select the pipeline under **Pipelines**.
+3. Click **Subscribe**.
+
+Subscriptions apply as soon as you make them and are not held by the agent's save bar. A running pipeline picks up a new subscriber without restarting, so you can subscribe an agent to a live pipeline at any time.
+
+### When a pattern produces a signal \[#pattern-emission]
+
+A pattern signals an agent only if the agent subscribed after that pattern last emitted a signal. This has two consequences worth knowing before you rely on it:
+
+* An agent is notified about each pattern once, for as long as the reducer keeps that pattern in its state. A pattern that keeps occurring does not keep starting investigations, so a pattern that matches a high volume of logs does not flood an agent. A pattern the reducer drops from its state and later meets again counts as new, and signals its subscribers a second time.
+* Subscribing gives you no backlog. An agent you subscribe today is never notified about occurrences that already happened. It is notified the next time any pattern matches, including a pattern the pipeline flagged before you subscribed, because that agent is newer than the pattern's last emission.
+
+So subscribing an agent to an established pipeline can produce a burst of investigations, one for each of its recurring patterns as that pattern next matches, and then settle down to one per newly detected pattern. Expect that burst on a busy pipeline and set the agent's concurrency limit before you subscribe. See [Control how many signals reach an agent](#volume).
+
+## Send specific events with an agent signal sink \[#agent-signal-sink]
+
+New-pattern signals tell an agent about behavior that is new. When you want an agent to investigate behavior you can describe instead, route a SQL output in the pipeline to the agent signal. Every event that output emits becomes a signal, so you decide exactly what reaches the agent by writing the SQL.
+
+This mechanism does not use subscriptions. The pipeline names the agents directly, so an agent can receive these signals without appearing in its own **Subscriptions** step.
+
+To configure it:
+
+1. In the pipeline, add a SQL transform whose output is routed to the agent signal. The routed output must produce log events.
+2. In the pipeline's sinks, edit the agent signal sink and select the agents in the **Agents** field.
+3. Optionally enter **Context**, which is guidance sent with every signal from this pipeline, such as which team owns the service or what an acceptable remediation is. A context can be up to 4,096 characters.
+
+The sink and the route are two halves of one configuration, and Grepr saves the pipeline only when both are present. A pipeline with a routed output needs a sink naming at least one agent, and a sink cannot remain after you remove its last route. When you stop sending signals from a pipeline, remove the route and the sink together.
+
+Because every matching event becomes a signal, a SQL output that matches broadly can produce far more investigations than an agent can run. Write the output to match the events you would want to look at yourself, then check the agent's queue after the change. See [Control how many signals reach an agent](#volume).
+
+To learn more about SQL transforms, see [_](/transforms/sql-transform).
+
+## Subscribe an agent to a Grepr Agent integration \[#webhook-sources]
+
+A Grepr Agent integration turns events from another system into investigations. Every event it accepts starts an investigation on each subscribed agent, with no pattern detection or deduplication in between.
+
+1. On the agent's page, go to the **Subscriptions** step.
+2. In the **Subscribe to a signal source** menu, select the integration under **Grepr Agent**.
+3. Click **Subscribe**.
+
+Subscribe more than one agent to an integration when you want different agents to examine the same event differently, such as one that diagnoses and one that checks for a security concern. Each subscribed agent gets its own investigation of the event.
+
+To create an integration and send events to it, see [_](/integrations/grepr-agent-webhooks).
+
+## Unsubscribe an agent \[#unsubscribe]
+
+On the agent's **Subscriptions** step, remove the source from the table and confirm. The agent stops investigating that source's signals. Investigations already running finish.
+
+Detach an agent from its pipelines and from the Grepr Agent integrations that name it before you delete it, because Grepr refuses to delete an agent either one still targets. A pipeline that names the agent in its agent signal sink is not covered by that check, so clear the agent from the sink's **Agents** field yourself. Because a sink keeps at least one agent, name another in its place or remove the sink with the routes that feed it. See [_](/ai-agents/create-an-agent#delete).
+
+## Control how many signals reach an agent \[#volume]
+
+Because subscriptions carry no filters, the number of investigations an agent runs is set by the sources you subscribe it to and the limits on the agent itself:
+
+* Narrow what the source emits. For a pipeline signal, make the SQL output match fewer events. For a webhook, send fewer events from the system at the other end. This is the only way to reduce signals rather than drop them.
+* Cap the agent's concurrency. Choose how many investigations run at once and whether extra signals queue or are discarded. See [_](/ai-agents/create-an-agent#concurrency).
+* Expire stale queued signals. Set a maximum queue wait so a signal that has waited too long is dropped rather than investigated late.
+* Cap the tokens. A per-window token budget on the agent bounds its spend whatever the signal volume. See [_](/ai-agents/create-an-agent#window-limits).
+
+New-pattern signals need less of this than the other sources, because a pattern notifies an agent once rather than on every occurrence.
+
+## Frequently Asked Questions
+
+### How do I make a Grepr pipeline trigger AI agent investigations?
+
+Select Emit new-pattern signals to AI agents in the pipeline reducer's advanced configuration, then subscribe the agent to that pipeline on the agent's Subscriptions step. Grepr refuses a subscription to a pipeline that has the option off, and a pipeline needs a log reducer or a pattern matcher to emit these signals at all.
+
+### Why didn't my agent investigate a log pattern again?
+
+A pattern signals an agent only if the agent subscribed after that pattern last emitted a signal, so a pattern that keeps occurring does not keep starting investigations for an agent that has already seen it. A newly subscribed agent is different: it is newer than every previous emission, so it is notified the next time each pattern matches, which can produce a burst of investigations when you subscribe to an established pipeline.
+
+### Can I filter which signals reach a Grepr AI agent?
+
+Not on the subscription, which carries no filters or conditions. You narrow what an agent investigates by changing the source: make a routed SQL output match fewer events, or send fewer webhook events. You can also cap the agent's concurrency, expire stale queued signals, and cap its token budget.
+
+### What is the difference between a new-pattern signal and an agent signal sink?
+
+A new-pattern signal fires when the reducer detects a log pattern it has not seen before, and the agent is chosen by subscription. An agent signal sink sends every event matched by a SQL output you routed to the agent signal, and the pipeline names the agents directly rather than using subscriptions.
+
+### Do I need to restart a pipeline after subscribing an agent?
+
+No. A running pipeline picks up a new subscriber without restarting, and subscriptions apply as soon as you make them.

package/build/dist/docs-index/470aa38e-db04-429d-bd83-23a2cf8851f0.txt

@@ -0,0 +1,113 @@
+Process data in Grepr pipelines using built-in tools for parsing, filtering, enrichment, and transformation of log events.
+
+# Transform data in a Grepr pipeline
+
+A Grepr transform is a processing step that modifies, enriches, or restructures data as it flows through a pipeline. As records move through a pipeline, transforms allow you to parse structured and semi-structured data, filter records, and use a familiar SQL interface to perform more complex transformation of records as they move through a pipeline. Transforms are configured as pipeline steps that process data sequentially. Each transform receives input data, applies its logic, and passes the result to the next step in the pipeline.
+
+Most transforms are available in the Grepr pipelines UI. Some transforms are available only in the Grepr REST API or provide more capabilities when used with the API, such as [filters](#filter) and [branching the processing of records](#message-routing) based on query matches.
+
+The following sections describe the transforms available in Grepr pipelines.
+
+## Transform semi-structured records with the Grok parser \[#grok-parser]
+
+The Grok transform parses unstructured text using pattern matching with regular expressions and named capture groups. Use this transform to extract fields from log lines, error messages, and other text-based data where you need to identify specific patterns and convert them to structured fields.
+
+See [Grok parser](/transforms/grok).
+
+## Convert JSON messages into structured objects \[#json-parser]
+
+The JSON parser transforms JSON strings into structured JSON objects. This transform handles nested objects, arrays, and various data types, making it useful for processing API responses, configuration data, and structured log entries.
+
+See [Transform JSON strings into JSON objects](/transforms/json-parsing).
+
+## Restructure JSON objects with a remapper \[#remapper]
+
+The remapper transform moves or copies attributes to top-level fields or to tags in a JSON object. You can also use rename rules to move attribute values from one path to another within the same event. In the pipelines UI, a remapper with customizable default attributes is automatically added to a pipeline.
+
+See [Remap JSON attribute fields to top-level log event fields](/transforms/remapper).
+
+## Transform records with SQL \[#sql-transform]
+
+The SQL transform allows you to use ANSI standard SQL queries to filter, transform, and enrich data records. The SQL transform provides a familiar SQL interface to perform a number of data processing and transformation tasks.
+
+You can use the SQL transform in the Grepr UI or REST API. In the UI, the SQL transform is available when you configure filters.
+
+To learn about using the SQL transform in the Grepr API, see the [SQL Operation specification](/apis/api-spec#schema/SQLOperation).
+
+For a complete reference and examples, see [Transform events with SQL](/transforms/sql-transform).
+
+## Filter records based on conditions \[#filter]
+
+The Filter transform includes or excludes data records based on specified conditions. You can create filters using familiar query interfaces, such as SQL, as well as Datadog and New Relic log query-like syntaxes.
+
+In the Grepr pipelines UI, filters are located in predefined locations in the pipeline. To learn how to configure filters, see [Filter events in a Grepr pipeline](/transforms/filter-events).
+
+To have more flexibility for where filters are included in a pipeline, use the REST API. See [LogsFilter](/apis/api-spec#schema/LogsFilter).
+
+## Reduce log volumes with dynamic aggregation \[#reducer]
+
+The Grepr log reducer uses clustering algorithms to identify patterns in your log data and aggregate similar log messages. The output of this aggregation includes summaries and samples of similar messages. The log reducer is a core step in a log reduction pipeline, where it runs before processed log events are sent to your configured sinks. By sending summaries of similar messages rather than multiple events with redundant information, Grepr significantly reduces the volume of shipped logs and your observability costs. The log reduction pipeline also persists the complete set of raw logs to a low-cost data lake, enabling you to analyze and troubleshoot issues when necessary.
+
+To learn more about how Grepr reduces log volumes with dynamic aggregation, see [Reduce noise and improve the usability of your logs with the log reducer](/transforms/reducer).
+
+To learn how to create a log reduction pipeline, see [Tutorial: Build your first Grepr pipeline](/tutorials/first-pipeline).
+
+To learn how to use the resulting summarized log events in your observability platform along with raw logs stored in Grepr, see [Troubleshoot incidents with Grepr-processed data and your observability tool](/tutorials/troubleshooting-example).
+
+## Transform and enrich log messages with the REST API \[#log-transform-action]
+
+You can use the LogTransformAction in the REST API to specify actions that transform log messages, such as adding or removing attributes and tags. See [LogTransformAction](/apis/api-spec#schema/LogTransformAction).
+
+## Route the processing of messages based on query matches \[#message-routing]
+
+You can route log messages to be processed by different pipelines based on query matches. Because the pipelines UI doesn't support branching, Grepr recommends creating multiple pipelines that ingest data using the same source, and then use filters to route data to the correct pipeline.
+
+Sending logs to different destinations, rather than processing them differently, is a separate problem with its own approaches. See [_](/solution-guides/route-logs-to-several-accounts).
+
+You can also use the REST API to create more complex pipeline configurations. See [LogsBranch](/apis/api-spec#schema/LogsBranch).
+
+## Frequently Asked Questions
+
+### What transforms are available in Grepr pipelines?
+
+Grepr provides several transform types: Grok parser for parsing unstructured text with pattern matching, JSON parser for converting JSON strings into structured objects, remapper for restructuring JSON fields and attributes, SQL transform for complex filtering and enrichment using SQL queries, and Filter transform for conditional record processing. Most transforms are available in the UI, while some advanced options are available via REST API.
+
+### When should I use the Grok parser transform?
+
+Use the Grok parser when you need to extract structured data from unstructured text logs. It's ideal for parsing error messages, application logs, system logs, and other text-based data where you need to identify specific patterns and convert them into structured fields using regular expressions and named capture groups.
+
+### When should I use the JSON parser transform?
+
+Use the JSON parser when your log messages contain JSON strings that need to be converted into structured JSON objects. This is useful for processing API responses, configuration data, and structured log entries. The JSON parser handles nested objects, arrays, and various data types automatically.
+
+### What is the remapper transform and when is it used?
+
+The remapper transform moves or copies attributes to top-level fields or to tags in a JSON object. It's useful for standardizing log event structure by moving well-known fields like message, severity, and host from nested attributes to top-level fields. You can configure whether the source attribute is preserved or removed after remapping. The remapper also supports rename rules for moving attribute values from one path to another. The remapper is automatically added to pipelines in the UI with customizable default attributes.
+
+### When should I use the SQL transform?
+
+Use the SQL transform when you need complex filtering, transformation, or enrichment of log records. SQL provides a familiar interface for advanced operations like conditional logic, string manipulation, aggregations, and joining data. It's available in the UI for filters and via REST API for more flexibility.
+
+### Can I combine multiple transforms in a pipeline?
+
+Yes, transforms are configured as sequential pipeline steps. Each transform receives input from the previous step, applies its logic, and passes the result to the next step. This allows you to create complex data processing workflows by combining parsing (Grok), restructuring (remapper), and filtering/enrichment (SQL) transforms.
+
+### What is the Filter transform used for?
+
+The Filter transform includes or excludes data records based on specified conditions. You can use filters with SQL, Datadog, and New Relic-like query syntaxes. In the UI, filters are located in predefined pipeline positions, while the REST API provides more flexibility for filter placement.
+
+### Can I use the REST API for more advanced transform options?
+
+Yes, the REST API provides access to advanced transform options not available in the UI. For example, you can use LogTransformAction to add or remove attributes and tags, LogsBranch for complex message routing based on query matches, and more flexible filter placement. See the API specification for complete details on transform capabilities.
+
+### How do I choose between Grok and SQL transforms?
+
+Use Grok when you need pattern-based parsing of unstructured text to extract specific fields. Use SQL when you need complex conditional logic, calculations, string transformations, or filtering. Grok is specialized for text parsing, while SQL is more general-purpose for data manipulation and enrichment.
+
+### How does Grepr reduce log volumes and observability costs?
+
+Grepr uses clustering algorithms to identify patterns in log data and aggregates similar log messages. Instead of sending multiple redundant log events, Grepr sends summaries and samples of similar messages to your observability platform. This significantly reduces the volume of shipped logs while retaining the ability to analyze and troubleshoot issues. Raw logs are retained in a low-cost data lake for future reference.
+
+### What happens if a transform fails on a record?
+
+Transform behavior depends on the specific transform type and configuration. Parsing errors (like Grok or JSON parsing) typically skip records or add error attributes depending on your configuration. SQL transforms filter out records that don't match conditions. Review transform-specific documentation for error handling details.

package/build/dist/docs-index/47127665-876f-449a-abeb-c79d589a0a1a.txt

@@ -0,0 +1,125 @@
+Connect a model provider with a Grepr LLM integration, and cap how many tokens your agents consume per time window.
+
+# Configure LLM provider connections with a Grepr integration
+
+An LLM integration holds the credentials Grepr uses to call a large language model provider. Grepr AI agents can use LLM integrations for two purposes: a generative model used for reasoning, or an embedding model used for similarity analysis.
+
+An LLM integration can be assigned a token budget, which is a mechanism that caps the amount of tokens your agents can spend. When several agents share one integration, the budget applies to all of them together.
+
+> LLM integrations, along with the rest of the Grepr AI agent features, are in a closed beta. To request access, contact <support@grepr.ai>.
+
+## Requirements
+
+To create an LLM integration, you need:
+
+* The credential your provider requires, which is an API key for most providers, or a gateway URL and a key for the gateway.
+
+## Choose a provider \[#providers]
+
+An LLM integration serves one of two purposes, so create the one that matches what you need.
+
+For the model an agent reasons with, create an integration for your model provider. You can also create a gateway integration to route your agents through a gateway you run, which reaches whatever models you configure it with, so use one to choose the model yourself, apply your own routing rules, or keep model traffic inside your own infrastructure.
+
+For the embedding model that agent memory uses, create an integration for a provider that supplies embeddings. One integration can serve both purposes, so a single integration is often enough to run an agent with memory turned on.
+
+The **Type** menu in the **Add LLM** dialog lists the providers available to you.
+
+Don't see your provider in the list? Send a request to <support@grepr.ai>.
+
+## Create an LLM integration \[#create]
+
+1. On the **Integrations** page, next to the **LLMs** section heading, click **Add new**.
+2. In the **Add LLM** dialog, select the provider from the **Type** menu.
+3. Complete the remaining fields, which depend on the provider you selected.
+4. Click **Create**.
+
+You cannot change an integration's type after you create it. To move to a different provider, create a new integration and point your agents at it.
+
+Select the tab for your provider to see the fields it requires:
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **API Key** | Your Anthropic API key. |
+| **Max tokens per window** | The total tokens that all agents using this integration can consume in each window. Leave empty for the default of 20,000,000. |
+| **Max tokens window (hours)** | The length of the budget window. Leave empty for the default of 1 hour. |
+
+An Anthropic integration serves as an agent's model. Anthropic does not supply embeddings, so an agent with memory turned on also needs a Gemini or OpenAI integration for its embedding model.
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **API Key** | Your Gemini API key. |
+| **Max tokens per window** | The total tokens that all agents using this integration can consume in each window. Leave empty for the default of 20,000,000. |
+| **Max tokens window (hours)** | The length of the budget window. Leave empty for the default of 1 hour. |
+
+A Gemini integration can serve as both an agent's model and the embedding model for agent memory.
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **Gateway URL** | The base URL of your LiteLLM proxy, such as `https://litellm.example.com/team-a`. Required. |
+| **Virtual key** | The LiteLLM virtual key Grepr authenticates with. |
+| **Validate virtual key when saving** | Turn this on to have Grepr verify the virtual key against the gateway before it saves the integration. |
+| **Max tokens per window** | The total tokens that all agents using this integration can consume in each window. Leave empty for the default of 20,000,000. |
+| **Max tokens window (hours)** | The length of the budget window. Leave empty for the default of 1 hour. |
+
+Grepr reaches whatever models your gateway exposes, so the model names available to an agent are the ones your LiteLLM configuration routes.
+
+| Field | Description |
+| --- | --- |
+| **Name** | A name for the integration, used to identify it when you configure an agent. |
+| **API Key** | Your OpenAI API key. |
+
+An OpenAI integration provides the embedding model that agent memory uses.
+
+## Cap token consumption with a budget window \[#max-tokens]
+
+An integration that serves an agent's model carries a token budget, which is what caps the spend of every agent sharing it. The budget has two settings:
+
+* **Max tokens per window** is the total tokens every agent sharing the integration can consume in one window.
+* **Max tokens window (hours)** is the length of that window. The value must divide 24 evenly, so the valid lengths are 1, 2, 3, 4, 6, 8, 12, and 24 hours. Windows are aligned to UTC.
+
+Before it starts an investigation, Grepr reserves the tokens that investigation is allowed to consume and checks the reservation against two budgets: the integration's budget, and the agent's per-window budget. Both must have room. An agent whose own budget is untouched still waits when the shared integration has none left, so when investigations stop starting, check which of the two is exhausted on the agent's page before you raise a limit. To learn more about the agent-level settings, see [_](/ai-agents/create-an-agent#limits).
+
+## Update an API key \[#update-key]
+
+To replace a key, click the three-dot menu on the integration card, select **Edit**, enter the new key, and click **Save**. Every agent using the integration picks up the new key automatically.
+
+## Grant team access \[#team-access]
+
+When you have teams in your Grepr organization, you can grant access to the integration to one or more of those teams. To configure team access when you create or edit an integration:
+
+1. In the **Grant Team Access** section, click the plus sign icon (+).
+
+2. Select the team or teams that should be granted access to the integration.
+
+3. Click **Create**.
+
+To learn more, see [Manage teams in the Grepr platform](/admin/manage-teams) and [Permissions in the Grepr platform](/grepr-platform/permissions).
+
+## View token usage \[#usage]
+
+Each LLM integration card on the **Integrations** page charts the tokens its agents consumed, broken down by token type, and shows how much of the budget window remains. The card totals every agent sharing the integration and lists which agents those are, so to see how much one agent is spending, open that agent's page.
+
+## Frequently Asked Questions
+
+### Which LLM providers can a Grepr AI agent use as its model?
+
+Create an LLM integration for your model provider, or a gateway integration to route your agents through a gateway you run, which reaches whatever models you configure it with. Use a gateway to choose the model yourself, apply your own routing rules, or keep model traffic inside your own infrastructure. The Type menu in the Add LLM dialog lists the providers available to you, and Grepr adds integrations continuously, so contact support\@grepr.ai to get connected to the provider you use.
+
+### Which LLM providers can Grepr use for agent memory embeddings?
+
+Create an LLM integration for a provider that supplies embeddings. One integration can serve as both an agent's reasoning model and its embedding model, so a single integration is often enough to run an agent with memory turned on.
+
+### How does Grepr cap the tokens my AI agents consume?
+
+An LLM integration that serves an agent's model carries a max-tokens budget and a window length in hours that must divide 24 evenly. Grepr reserves an investigation's tokens up front and requires room in both the shared integration budget and the agent's own per-window budget before the investigation starts.
+
+### Can I change an LLM integration's provider after creating it?
+
+No. The type is fixed when you create the integration. To move to a different provider, create a new integration and point your agents at it.
+
+### Why have my agent's investigations stopped starting?
+
+The most common cause is an exhausted token budget. Because several agents can share one LLM integration, the shared budget can run out while the agent's own budget is untouched. The agent's page reports which of the two blocked the investigation and when the window resets.