@grepr/cli 1.11.5-c840124 → 1.11.5-de00b67

package/build/dist/docs-index/11f6a885-1348-4e5d-95e6-9895dd6ae017.txt

@@ -0,0 +1,21 @@
+Guides that work through common Grepr situations end to end, showing the ways you can configure a pipeline to solve each one.
+
+# Solution guides
+
+A solution guide works through a situation you are likely to meet in production, rather than a single feature. A Grepr pipeline is a free-form processing graph, so most situations have more than one good shape. Each guide states the problem, then walks through the ways you can configure Grepr for it.
+
+Use these guides when you know what you want to achieve but not yet how to shape your pipelines around it. To learn a feature on its own, see the reference documentation for [pipelines](/pipelines), [transforms](/transforms), and [integrations](/integrations). To work through the product step by step, see [_](/tutorials).
+
+## Route logs to several vendor accounts
+
+Your logs belong to more than one account in your observability platform, because separate teams, environments, or business units each own their own. This guide shows two ways to get each log, and each summary of those logs, to the account that owns it: a pipeline for each group, or one pipeline whose reducer groups on a routing key and whose sinks each filter on it. See [_](/solution-guides/route-logs-to-several-accounts).
+
+## Frequently Asked Questions
+
+### What is a Grepr solution guide?
+
+A solution guide works through a situation you are likely to meet in production rather than a single feature. A Grepr pipeline is a free-form processing graph, so most situations have more than one good shape. Each guide states the problem, then walks through the ways you can configure Grepr for it.
+
+### How is a solution guide different from a tutorial?
+
+A tutorial teaches the product step by step, starting from nothing. A solution guide assumes you know what you want to achieve and shows you the ways you can shape your pipelines around it.

package/build/dist/docs-index/6c870d90-1524-415c-b045-94b9eac9c372.txt

@@ -0,0 +1,15 @@
+# ExceptionImpact
+
+Estimated passthrough for one parsed alert query against one dataset
+
+**Type**: `object`
+
+## Properties
+
+- name: measuredAt (optional)
+  type: string
+  description: When the estimation run that produced this percentage completed. Absent when the age of the measurement is not known; that is not the same as freshly measured.
+
+- name: percentage (required)
+  type: number
+  description: Estimated percentage of the dataset's raw log volume this query matches. Honouring the query as a pipeline exception passes approximately this share of the data through without aggregation.

package/build/dist/docs-index/8b166fd1-5601-42e9-8125-77a3145edd94.txt

@@ -0,0 +1,33 @@
+# Get parsed alert query impacts for an integration and dataset
+
+**GET** `/v1/integrations/{integrationId}/exceptions/impacts`
+
+**Operation ID**: `getIntegrationExceptionImpactsByDataset`
+**Summary**: Get parsed alert query impacts for an integration and dataset
+Returns the estimated percentage of the dataset's raw log volume each of the integration's parsed alert queries matches, with the time that estimate was measured. Queries that have not been estimated are absent from the response rather than reported as zero. The dataset must be one of those returned by the estimation-datasets endpoint for this integration.
+
+## Tags
+- Integration Exceptions
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+- **datasetId** (required) - query
+  - Dataset the estimates are scoped to
+  - Type: string
+
+## Responses
+
+### 200
+
+Impact estimates retrieved
+
+- **Content-Type**: `application/json` / object
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration not found, or the dataset is not reachable from it.

package/build/dist/docs-index/{da3cf630-5eae-4cc7-b454-ac83a7862ffd.txt → 8b6a5d24-e9c0-4402-b91b-00691158261e.txt}

@@ -62,6 +62,8 @@ You can use the LogTransformAction in the REST API to specify actions that trans
 
 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

package/build/dist/docs-index/{bec15343-e0cb-4150-8ef0-2f5a62d2f507.txt → 8eb5a2b7-e728-4dd9-9b1f-530d9e9b4077.txt}

@@ -4,7 +4,7 @@
 
 **Operation ID**: `getIntegrationExceptionImpacts`
 **Summary**: Get integration exception impacts for a pipeline
-Returns the per-exception impact percentages the runtime auto-sync threshold filter would compare against for this pipeline/integration pair. The pipeline's sink dataset scopes the lookup; exceptions without an estimation row are absent from the response.
+Returns the per-exception impact percentages the runtime auto-sync threshold filter would compare against for this pipeline/integration pair, each with the time that estimate was measured. The pipeline's sink dataset scopes the lookup; exceptions without an estimation row are absent from the response rather than reported as zero.
 
 ## Tags
 - Pipeline Exceptions

package/build/dist/docs-index/8f63d9d2-1c18-41f3-b54d-992f251180f0.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.

package/build/dist/docs-index/{faaf380c-f44b-4d74-9605-d603c38e45c9.txt → 951cfc27-da1b-4230-8999-7574f3409f77.txt}

@@ -20,15 +20,19 @@ To modify the configuration settings in the UI, on the overview page for your pi
 
 ## Configure how messages are grouped \[#grouping-configuration]
 
-The **Grouping Configuration** section controls how incoming messages are partitioned into independent groups before pattern detection, and the level of similarity messages must meet to be considered part of the same pattern.
+Grouping controls how incoming messages are partitioned into independent groups before pattern detection, and the level of similarity messages must meet to be considered part of the same pattern.
 
-### Group-by values \[#group-by-configuration]
+### Group messages by a field \[#group-by-configuration]
 
-To control how the reducer partitions messages, enter a comma-separated list of tag keys and attribute paths in the **Group-by values** field. Messages are aggregated separately for each unique combination of values across the listed tags and attributes, so patterns from different services, hosts, or other dimensions are never merged. For example, the value `service, host, @http.url.path` aggregates messages independently for each unique combination of `service`, `host`, and the `http.url.path` attribute.
+Messages are aggregated separately for each unique combination of values across the fields you group on, so patterns from different services, hosts, or other dimensions are never merged. Grouping on `service`, `host`, and the `http.url.path` attribute aggregates messages independently for each unique combination of those three values.
 
-To specify attributes, prefix the attribute path with `@` and use dot notation for nested attributes. For example: `@http.url.path`. Enter tag keys using just the key name without any prefix.
+To group on a field, on the pipeline's **Reducer** step, click **Edit** on the **Fields** card, find the field, and set its behavior to **Match or split**. A field with this behavior is kept out of aggregation, so messages whose values for it differ are never merged into one pattern.
 
-Use this setting to retain the values of important fields by excluding them from aggregation. For example, to retain the values of high-cardinality identifiers, such as user IDs. To prevent a field from being aggregated, parse the field into an attribute using the **JSON Parser** or **Grok Parser** steps earlier in the pipeline, then add that attribute to the **Group-by values** field. See [Transform JSON strings into JSON objects](/transforms/json-parsing) and [Parse log messages to enrich log events with the Grok parser](/transforms/grok).
+Attribute paths are written with an `@` prefix and dot notation for nested attributes, such as `@http.url.path`. Tag keys are written as the key name alone.
+
+Use grouping to retain the values of important fields by excluding them from aggregation, such as high-cardinality identifiers like user IDs. To keep a field that is currently inside the message, parse it into an attribute or a tag with the **JSON Parser** or **Grok Parser** step earlier in the pipeline, then group on that field. See [Transform JSON strings into JSON objects](/transforms/json-parsing) and [Parse log messages to enrich log events with the Grok parser](/transforms/grok).
+
+Grouping also decides how a summary can be routed, because a summary carries the tag values of the fields it was grouped on. To use grouping to send each group's logs to a different destination, see [_](/solution-guides/route-logs-to-several-accounts).
 
 ### Similarity threshold (%)