@grepr/cli 1.11.5-17c35fd → 1.11.5-1b47e00

package/build/dist/docs-index/08321a1e-893d-4eff-83b8-1e12ddb30b38.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/08cf97e3-fc73-47ec-89f7-d345fc4e3b21.txt

@@ -0,0 +1,168 @@
+Turn on Grepr AI agent memory so an agent records what it concluded, counts recurrences, and searches past investigations during a new one.
+
+# Remember past investigations
+
+Without memory, every investigation starts from nothing. An agent that diagnosed a problem last week reaches the same conclusion the same slow way this week, and nobody learns that the problem has now happened five times.
+
+*Memory* changes that. An agent with memory enabled records what it concluded when it reaches a diagnosis, recognizes when a later investigation reaches the same conclusion and counts the recurrence, and searches those records at the start of a new investigation to find out whether it has seen this before.
+
+Both halves show up in the investigation's tool calls. A memory search runs near the start, before the agent has looked at anything else, and the record is written at the end, when it has a diagnosis.
+
+The agent decides what to record and whether something is a recurrence. Grepr does not extract conclusions on its behalf or merge records by similarity, because the investigating agent is the only thing that saw the evidence.
+
+Memory is off until you turn it on and choose where the memories are stored.
+
+## What an agent records \[#what-recorded]
+
+An agent records at most one memory per investigation, written when it reaches a diagnosis rather than after the fact. Each memory holds:
+
+| Field | What it holds |
+| --- | --- |
+| Title | A short name for the problem. |
+| Symptoms | What was observed. |
+| Root cause | What the agent concluded was responsible. |
+| Root cause confidence | Whether the cause is **confirmed**, **suspected**, or **unknown**. |
+| Ruled out | Causes the agent checked and eliminated, so a later investigation does not repeat that work. |
+| Resolution | What resolved it, or what was attempted. |
+| Significance | How much the conclusion matters. See [Significance](#classification). |
+| Entity tags | The services, pipelines, and environments the memory is about. See [Entity tags](#tagging). |
+| Recurrence count | How many investigations reached this same conclusion. |
+
+An agent can correct its own memory for an investigation while that investigation is running, so an early diagnosis it later disproves does not stay on the record. Correcting a memory does not count as a new recurrence.
+
+### Significance \[#classification]
+
+Significance is how an agent classifies what it found, and it decides how the memory can be found later:
+
+| Significance | Meaning |
+| --- | --- |
+| Incident | A real problem was identified. |
+| Observation | Not a problem, but a conclusion worth keeping. |
+| Inconclusive | The agent could not determine whether there was a problem. |
+| Benign | Triaged as no problem. |
+
+Benign memories are recorded but not indexed for search by meaning or by text. They are reachable only by a timeline search over their entity tags. This keeps the large number of routine all-clear findings out of the way of searches for real problems, at the cost of making them harder to find. If you want an agent to notice that a given service has been triaged as benign many times, search the timeline for that service rather than searching by text.
+
+## Turn on memory \[#enable]
+
+Memory needs somewhere to store its search index and a model to build that index with, so there are three things to set up.
+
+### Step 1: Create a vector index integration \[#vector-index]
+
+1. On the **Integrations** page, next to the **S3 Vector Index** section heading, click **Add new**.
+2. In the **Add Vector Index** dialog, enter a **Name** and the number of **Dimensions** the embedding model you plan to use produces, then click **Create**.
+
+The dimensions must match the model's output, so choose the embedding model first and use its dimension count. An index's dimensions are fixed after creation.
+
+### Step 2: Create an embedding integration \[#embedding-integration]
+
+Memory embeds each record with a model from an LLM integration that provides embeddings. If you do not have one, create it before you continue. See [_](/integrations/llm).
+
+An agent's reasoning model and its embedding model are separate choices. An agent can reason with one integration and embed with another.
+
+### Step 3: Turn on memory for the agent \[#agent-memory]
+
+1. On the agent's page, go to the **Memory** step.
+2. Turn on **Remember past investigations**.
+3. Under **Storage**, select the **Vector index integration**, the **Embedding credentials**, and the **Embedding model**.
+4. Save the agent.
+
+Grepr creates the search index when you create the vector index integration in Step 1, and discards the integration if the index cannot be created. Saving the agent then checks that the embedding model actually works against that index, by embedding a test value with it. So a wrong model or an unusable credential stops the save rather than surfacing later as memories that were never indexed.
+
+### Choose an embedding model and keep it \[#embedding-model]
+
+A memory is embedded with the model the agent had when it was recorded, and a query can only be compared against embeddings from the same model. Changing an agent's embedding model therefore cuts its new memories off from the ones it already recorded, as far as searching by meaning is concerned. Treat the choice as long lived.
+
+Using the same model across several agents does not pool their memories into one semantic search. A search by meaning always targets one agent, as described next.
+
+## How an agent searches its memory \[#search-modes]
+
+A search runs in exactly one of three modes, and which mode fits depends on what the agent is trying to find:
+
+| Mode | What it finds | Use it to answer |
+| --- | --- | --- |
+| Semantic | Investigations whose conclusions mean something similar to the query. | Has a problem like this happened before? |
+| Text | Investigations mentioning specific words, using full-text search. | Has this exact error string or identifier come up before? |
+| Timeline | Investigations about given entities, ordered by time. | What has been happening to this service recently? |
+
+Semantic search finds a past incident described in different words, which text search misses. Text search finds a literal, such as an error code or a host name, which semantic search can rank poorly. Timeline search needs entity tags rather than a query, and it is the only mode that returns benign memories.
+
+The modes also differ in how much they cover, which matters when you read an empty result:
+
+* A semantic search covers one agent at a time, because a query is only comparable against embeddings made with that agent's model. An empty semantic result means nothing similar was found within what the search could reach. It is not evidence that the agent recorded nothing similar, and it is not evidence that your organization has not seen the problem. A memory embedded with a model the agent no longer uses is unreachable until it is embedded again, and a search that cannot reach the embedding provider returns empty as well. When an empty result matters, confirm it with a text or timeline search, which read the records directly.
+* A text or timeline search covers every agent in your organization by default, so it is the one to use when you want the organization's whole history.
+
+So to find out whether any agent has seen something, search by text or timeline, or repeat the semantic search against each agent you care about.
+
+A result carries the memory's content along with its recurrence count, how long ago it was recorded, when it was last seen, and whether it is active, recent, or historical. There is no relevance score, because the agent judges from the content and the provenance rather than a ranking number.
+
+Search returns at most 50 results and has no pagination, so a broad query can be incomplete. Narrowing by entity tags or by significance is more effective than raising the limit.
+
+## Entity tags \[#tagging]
+
+Entity tags are what make memories findable by the thing they are about, such as a service, a pipeline, or an environment. Each memory carries two kinds:
+
+* Tags Grepr derives from the triggering signal, which identify the source and the signal type.
+* Tags the agent adds, which name the entities it concluded the memory is about.
+
+Grepr derives its tags using a mapping per signal type, which extracts values from the signal payload by path. The shipped mappings cover the common cases:
+
+| Signal type | Tags derived from the signal |
+| --- | --- |
+| Log pattern | The pipeline, the pattern, and the service, environment, and Kubernetes namespace from the sample log event. |
+| Webhook | The integration, and the service and host from the payload. |
+| Manual | The signal type only. |
+
+The webhook mapping reads the service and host from field names Grepr expects. If your payloads name those fields differently, add a mapping so the tags resolve. On the agent's **Memory** step, under **Entity tags**, add a mapping for the signal type, then add each tag key with the paths to read it from. Grepr tries the paths in order and uses the first that resolves.
+
+Consistent tag values matter more than complete ones. A service tagged `checkout` in some memories and `checkout-svc` in others splits its history in two, and a timeline search finds only half. Grepr gives an agent the tag values already in use in your organization when it searches, so an agent that searches before recording reuses existing values rather than inventing new ones.
+
+## Who can read and write memories \[#scope]
+
+* Reads are organization-wide. Any agent can search any other agent's memories in your organization. Operational history is only useful shared, so an agent investigating a service finds what another agent concluded about the same service. Permission is uniform across the modes, but coverage is not: a semantic search still examines one agent at a time. See [How an agent searches its memory](#search-modes).
+* Writes are owner-only. A memory can be written or corrected only by the agent that ran the investigation, so one agent cannot overwrite another's conclusions.
+
+When an agent finds that a past memory describes what it is now seeing, it links its investigation to that memory, which raises the recurrence count rather than creating a near-duplicate record. Each contributing investigation counts once.
+
+Memories outlive the agent that wrote them. Deleting an agent leaves its memories searchable by your other agents.
+
+## Search memories from the CLI \[#cli]
+
+The Grepr CLI searches the same memories an agent does, which is how you read what your agents have concluded.
+
+```bash
+# Find investigations mentioning a literal string
+grepr investigation:memory:search --mode text --query "connection refused" --limit 5
+
+# Find investigations whose conclusions are similar in meaning
+grepr investigation:memory:search --mode semantic --agent-id <agent-id> --query "intermittent ingestion failures"
+
+# See what has been happening to one service lately
+grepr investigation:memory:search --mode timeline --entity-tag entity:service=checkout
+```
+
+A semantic search needs an agent id, because a query can only be compared inside the index that agent embeds into. Text and timeline searches cover every agent in your organization by default. Timeline searches need at least one entity tag.
+
+The CLI is how you read what your agents have concluded outside of an investigation. To learn more about the CLI, see [_](/cli).
+
+## Frequently Asked Questions
+
+### What does Grepr AI agent memory store?
+
+One memory per investigation, holding a title, the symptoms, the root cause and the agent's confidence in it, the causes it ruled out, the resolution, a significance classification, entity tags, and a count of how many investigations reached the same conclusion.
+
+### What do I need to turn on agent memory?
+
+Three things: a vector index integration whose dimensions match your embedding model, an LLM integration that supplies the embedding model, and the embedding model name. Grepr creates the search index when you create the vector index integration. Saving the agent then checks that the embedding model works against that index, so a wrong model stops the save.
+
+### How does an agent search its memory?
+
+In one of three modes. Semantic search finds conclusions that mean something similar to the query, and covers one agent at a time. Text search finds specific words, such as an error code. Timeline search finds memories about given entities ordered by time, and is the only mode that returns benign memories. Text and timeline searches cover every agent in the organization by default.
+
+### Can one Grepr AI agent read another agent's memories?
+
+Yes, permission is organization-wide, so any agent can search any other agent's memories in your organization. Coverage differs by mode: text and timeline searches span every agent by default, while a search by meaning targets one agent at a time, because a query is only comparable against embeddings made with that agent's model. Writes are owner-only.
+
+### How do I read what my agents have remembered?
+
+Search them with the grepr investigation:memory:search command, choosing text, semantic, or timeline mode, or read them in an investigation that searched them. The Memory step of an agent holds the settings rather than the records.

package/build/dist/docs-index/0e7e742e-5b3f-441b-92d0-b08e5d9e325c.txt

@@ -0,0 +1,55 @@
+# Datadog
+
+The payload containing integration data.
+
+**Type**: `object`
+
+## Properties
+
+- name: additionalTags (required)
+  type: array of string
+  description: Tags to add when writing data to Datadog
+
+- name: apiKey (optional)
+  type: string
+  description: Masked API key for Datadog
+
+- name: apiKeys (optional)
+  type: array of `IngestKeyView`
+  description: The API keys configured for this integration (masked).
+
+- name: appKey (optional)
+  type: string
+  description: Masked App key for Datadog
+
+- name: clientToken (optional)
+  type: string
+  description: Client token for Datadog
+
+- name: dashboardFreshnessWindow (optional)
+  type: string
+  description: The active dashboard threshold: only dashboards viewed within it are imported as parsed queries. When unset, every dashboard is imported. Minimum one day.
+
+- name: exceptions (optional)
+  type: object
+  description: The imported exceptions from Datadog. This is a map from the vendor resource Id to the exception.
+
+- name: filterQuery (required)
+  type: string
+  description: Filter to apply when reading any data from the Datadog API
+
+- name: includeNeverViewedDashboards (optional)
+  type: boolean
+  description: When the active dashboard threshold is set, whether dashboards that were never viewed are still imported. Unset means they are.
+
+- name: sendKeyId (optional)
+  type: string
+  description: Identifier of the API key used to send data back to Datadog. Defaults to the only key when unset.
+
+- name: site (required)
+  type: string
+  description: Datadog site URL
+
+- name: validateKeysOnSave (optional)
+  type: boolean
+  description: Indicates whether to validate the API and App keys when saving the keys.

package/build/dist/docs-index/2b3d1e87-cbeb-41ca-88ab-cfc28b56a7c6.txt

@@ -0,0 +1,38 @@
+# Pause or resume an agent
+
+**PUT** `/v1/agents/{id}/state`
+
+**Operation ID**: `setState`
+**Summary**: Pause or resume an agent
+Sets the agent to PAUSED or ACTIVE. A paused agent runs no investigations: signals from every source are dropped, manual starts and resumes are refused, and queued investigations wait until the agent is resumed. Pipelines keep marking new patterns as sent, so after resuming, the agent usually reacts only to patterns that are new since then.
+
+## Tags
+- Agents
+## Parameters
+
+- **id** (required) - path
+  - Type: string
+
+## Request Body
+
+**Content-Type**: `application/json`
+
+**Schema**: `StateChangeRequest`
+
+## Responses
+
+### 204
+
+State set (or already set)
+
+### 400
+
+The state is not ACTIVE or PAUSED
+
+### 401
+
+Unauthorized
+
+### 404
+
+Agent not found

package/build/dist/docs-index/30559d7e-dc3a-40e0-acf7-a5b9adf171ab.txt

@@ -0,0 +1,21 @@
+# query
+
+**POST** `/v1/metrics/query`
+
+**Operation ID**: `query`
+**Summary**: No summary provided.
+## Tags
+- Status Metrics
+## Request Body
+
+**Content-Type**: `application/x-www-form-urlencoded`
+
+**Schema**: object
+
+## Responses
+
+### default
+
+default response
+
+- **Content-Type**: `application/json` / `QueryResult`

package/build/dist/docs-index/30aecc3f-f181-4504-a5bf-2f7ad38f2677.txt

@@ -0,0 +1,19 @@
+Learn how to create, run, and manage Grepr pipelines that process your telemetry data to improve value and reduce size before sending it to your observability platform.
+
+# Process your telemetry data with Grepr pipelines
+
+Grepr pipelines orchestrate data processing flows that ingest your telemetry data, such as logs and Application Performance Monitoring (APM) data produced by agents and collectors, transform and enrich the data, and deliver the resulting data to your observability platform.
+
+An example of a pipeline is a log or trace reduction pipeline that reduces the volume of duplicate, low-value events by creating summarized events that retain the context of the original events.
+
+## Trace reduction pipelines
+
+Trace reduction pipelines process the APM data produced by your applications and agents by applying configured transformations, sampling to create representative subsets of the data, and forwarding the results to your observability platform. Grepr uses a novel approach to identify and sample every path through your system. Sampling reduces the volume and cost of data sent to your observability platform, while the complete set of raw traces is retained in a Grepr data lake. If you use Datadog, you can also derive and forward metrics from your trace data to track trends across your traces without forwarding every trace. See [_](/pipelines/trace-pipelines).
+
+## AI agent signals and suggestions
+
+A log reduction pipeline can report each newly detected log pattern to your Grepr AI agents, so an agent investigates behavior that is new in your systems. An agent can also propose a change to the pipeline it investigated, such as a new Grok parser or an added SQL transform, which appears on the pipeline's **Suggestions** step for you to review and apply. To turn on signals, see [_](/transforms/reducer/configuration#agent-signals). To review a proposed change, see [_](/ai-agents/investigations#suggestions).
+
+## Agent sessions pipelines
+
+Agent sessions pipelines process the telemetry produced by coding agents such as Claude Code, Codex, and OpenCode. A coding agent reports its conversation as OpenTelemetry log events and its execution as OpenTelemetry spans, and neither signal is readable as a session on its own. An agent sessions pipeline reads both signals, reconstructs each run into a single session, and stores it in a Grepr data lake, so you can read the transcript, measure the tokens and cost the run consumed, and find the runs that failed. See [_](/pipelines/agent-sessions).

package/build/dist/docs-index/39e5d7c2-b96c-4c0c-96b7-05307beacb25.txt

@@ -0,0 +1,78 @@
+Two ways to send logs to several vendor accounts, by creating a pipeline for each group or by grouping the reducer and filtering each sink.
+
+# Route logs to several vendor accounts
+
+Your logs do not all belong in the same place. Separate teams, environments, or business units each own an account in your observability platform, and a log has to reach the account that owns it. Each account you send to is its own Grepr integration.
+
+A Grepr pipeline is a free-form processing graph rather than a fixed shape, so you can arrange this in more than one way. Here are two examples, and you can combine them.
+
+## Create a pipeline for each group \[#pipeline-per-group]
+
+Create one pipeline for each group of logs that belongs together, filter its source to that group, and give it the sink for that group's account.
+
+Each pipeline summarizes only its own logs, so you can tune each one on its own. Choose this when the groups need different configurations, or when you want them isolated from each other.
+
+To create a pipeline, see [_](/tutorials/first-pipeline). To limit what one ingests, see [_](/transforms/filter-events).
+
+## Group the reducer and filter each sink \[#grouped-sinks]
+
+Run a single pipeline, add a sink for each account, and filter each sink to that account's logs. Choose this when the groups have the same configuration, and you would rather manage one pipeline than several.
+
+Routing rests on a *routing key*, which is a field whose value names the account a log belongs to, such as `account` or `team`. Two settings act on it: the reducer groups on the key, and each sink filters on it.
+
+Grouping is what makes the filtering correct. A summary carries the values of the fields it was grouped on, so grouping on the routing key gives every summary exactly one account, and each sink's filter then matches its own account and no other.
+
+> Configure the grouping before you add the sinks, because leaving it out fails quietly. Without the routing key in the group-by, logs bound for different accounts aggregate together. A tag then carries every value the merged messages had, so every account receives the same summary, reporting counts that include the other accounts' logs. An attribute is merged instead, and the default merge strategy replaces values that differ with a wildcard, so no filter matches and the summary reaches no account.
+
+### Step 1: Put the routing key on every log \[#step1-routing-key]
+
+The routing key has to be on each log before the reducer sees it, holding one value per account. If your collectors already tag logs with the owning team or environment, use that tag. If the value is inside the message, parse it into an attribute or a tag first with the Grok parser or the JSON parser. See [_](/transforms/grok) and [_](/transforms/json-parsing).
+
+A tag and an attribute both work as the routing key. Choose one whose values are few and stable, because each value aggregates separately. Decide what happens to logs carrying no value for the key, which match no filter and so reach no account: give them a default value when you parse, or add a sink that catches them.
+
+### Step 2: Group the reducer on the routing key \[#step2-group]
+
+1. On the pipeline's **Reducer** step, click **Edit** on the **Fields** card.
+2. If the routing key is listed, set its **Behaviour** to **Match or split**.
+3. If it is not listed, enter it in the **Add field** row, set the **Behaviour** to **Match or split**, and click **Add**.
+4. Click **Save**.
+
+The **Match or split** behavior keeps a field out of aggregation, so messages whose values differ are never merged into one pattern. Enter tag keys plainly, and prefix attribute paths with `@`. An attribute is merged as well as grouped, and the default merge strategy keeps the value that every message in the group agrees on. If you set a different merge strategy for the routing attribute, check that it preserves that value rather than combining or discarding it. See [_](/transforms/reducer/configuration#attribute-configuration).
+
+### Step 3: Create a Grepr integration for each account \[#step3-integrations]
+
+Create one Grepr integration for each account you send to. An integration authenticates to a single account, so its credential is what decides where its logs land. Name each integration after its account, because that name is what you select when you add the sink. See [_](/integrations).
+
+### Step 4: Add a filtered sink for each account \[#step4-sinks]
+
+Repeat for each account:
+
+1. On the pipeline's **Sinks** step, click **Add sink**.
+2. In the **Sink** menu, select the integration for the account. Grepr fills in a **Name**, which you can change.
+3. In the **Query language** menu, select the syntax you want to write the filter in.
+4. In the **Filter Query** field, enter a query that matches only that account's logs, such as `team:platform`.
+5. Click **Add**, then save the pipeline.
+
+A sink with an empty filter forwards everything, so give each sink a filter query that matches it to one account. A sink's card reports its filter and shows **All messages** when it has none, which is how you spot one you missed. The filter runs on everything the reducer emits, so summaries, samples, passthrough messages, and exceptions all follow the same routing. To learn about the filter syntax, see [_](/queries/datadog) and [_](/queries/new-relic).
+
+## Frequently Asked Questions
+
+### Can one Grepr pipeline send logs to several accounts of the same vendor?
+
+Yes. Add one sink for each account, each pointing at that account's integration, and give each sink a filter that matches only that account's logs. Group the reducer on the same routing key the filters use, so that each summary belongs to exactly one account.
+
+### Why does the reducer need to group on the routing key?
+
+Without it, logs for different accounts aggregate together and the summary no longer identifies one account. If the key is a tag, the summary carries every value the merged messages had, so each account's filter matches it and every account receives counts that include the other accounts' logs. If the key is an attribute, the default merge strategy replaces the differing values with a wildcard, so no filter matches and the summary reaches no account.
+
+### Should I create a pipeline for each account or filter the sinks of one pipeline?
+
+Create a pipeline for each group when the groups need different reduction settings or different exceptions, or when you want them isolated. Filter the sinks of one pipeline when the groups share one reduction policy and you would rather keep a single pipeline to change.
+
+### What happens to logs that have no value for the routing key?
+
+They match no sink's filter and reach no vendor account. Give them a default value when you parse the routing key, or add a sink whose filter matches them so they land somewhere you can see.
+
+### Does a sink filter apply to summarized logs as well as raw ones?
+
+Yes. The filter runs on everything the reducer emits, so summaries, samples, passthrough messages, and exceptions all follow the same routing.