@grepr/cli 1.10.5 → 1.10.6-3845ea3

package/build/dist/docs-index/10fd92ef-1c64-473a-97ea-03c63d0732ce.txt

@@ -0,0 +1,182 @@
+Capture sessions from coding agents such as Claude Code, Codex, and OpenCode, then explore transcripts, execution spans, token usage, cost, and errors.
+
+# Capture and explore agent sessions
+
+An *agent session* is one complete run of a coding agent: the prompts you sent, the model calls the agent made, the tools it ran, the results those tools returned, and the tokens and cost it consumed. An *agent sessions pipeline* ingests the telemetry your agent already produces, reconstructs each session from it, and stores the result in a Grepr data lake so you can read the transcript, measure what the agent spent, and find the runs that failed.
+
+Coding agents report this activity as OpenTelemetry data, split across two signals. They describe what happened in the conversation as OTLP log events, and they describe how the run executed as OTLP spans. Neither signal is a session on its own, and neither is readable as a conversation without reassembly. An agent sessions pipeline reads both from the same integration and joins them into a session you can explore.
+
+> Agent sessions are enabled for each organization individually. To turn on agent sessions for your organization, contact <support@grepr.ai>.
+
+## What Grepr captures from an agent session \[#captured-data]
+
+From a supported agent harness, a session records:
+
+* The prompts you sent and the text the agent replied with.
+* Every tool call, with its arguments and the result the tool returned.
+* Token counts for each model call, broken down into input, output, cache reads, and cache writes.
+* The cost the harness reported for the run, when the harness reports one.
+* The model and provider that served each call.
+* Every error the agent encountered, joined back to the tool call that produced it.
+* The identity that ran the session and the duration of each step.
+
+How completely a session is captured depends on the harness and on how you configure it. A harness reports content only when you turn content logging on, and some harnesses do not report every field. Grepr labels these gaps rather than hiding them: a session names the content its harness never sent, and marks content the harness shortened as a truncated capture.
+
+## Anatomy of an agent session \[#session-model]
+
+Grepr presents every harness the same way, so a transcript reads alike whichever agent produced it.
+
+An *emitter* is the harness that produced a session, such as `claude-code`. It appears in the **Emitter** column of the sessions list, and it is how you tell one harness's sessions from another's when several report to the same dataset.
+
+A session is a sequence of *turns*, where each turn is one prompt and everything the agent did in response. A turn contains *events*, and the kinds that make up a transcript are:
+
+| Event kind | What it records |
+| --- | --- |
+| `user_message` | A prompt you sent to the agent. |
+| `model_call` | One request to a model, with its token counts and cost. |
+| `assistant_message` | Text the agent replied with. |
+| `tool_call` | A tool the agent invoked, with its arguments. |
+| `tool_result` | What a tool returned, and whether it failed. |
+
+A session records other kinds too, such as tool decisions and lifecycle events. Every event Grepr stored for a session, whatever its kind, is listed under **Raw events** in the session.
+
+Alongside the events, a session carries *execution spans*, which are the timing records for its model calls and tool executions. Events tell you what the agent did; spans tell you how long each step took and how the steps overlapped.
+
+## Supported agent harnesses \[#harnesses]
+
+Grepr recognizes the following harnesses and reports each one as the listed emitter. Grepr identifies a harness by the service name in its telemetry, so do not override `OTEL_SERVICE_NAME`. A session whose service name has been changed is not recognized, and its data reaches the data lake without being assembled into a session.
+
+| Harness | Emitter | Service name | Setup |
+| --- | --- | --- | --- |
+| Claude Code | `claude-code` | `claude-code` | [Configure Claude Code](/integrations/open-telemetry?tab=claude-code#configure-forwarding-to-grepr) |
+| Codex | `codex` | `codex_exec` or `codex_cli_rs` | [Configure Codex](/integrations/open-telemetry?tab=codex#configure-forwarding-to-grepr) |
+| OpenCode | `opencode` | `opencode` | [Configure OpenCode](/integrations/open-telemetry?tab=opencode#configure-forwarding-to-grepr) |
+
+Any harness that exports OTLP logs and traces can send data to an agent sessions pipeline, and that data is stored in your data lake. Grepr assembles sessions only for the harnesses listed here, so telemetry from another harness is searchable but does not appear in the Agent Sessions page.
+
+## Create an agent sessions pipeline \[#create-pipeline]
+
+An agent sessions pipeline reads a harness's two signals from a single OpenTelemetry integration. You attach the integration once, and the pipeline reads agent events from its OTLP logs endpoint and execution spans from its OTLP traces endpoint.
+
+### Step 1: Create an OpenTelemetry integration
+
+Create an OpenTelemetry integration to receive your agent's telemetry. Agent sessions require no special integration settings, so follow the instructions for [creating an OpenTelemetry integration](/integrations/open-telemetry#step1-create-integration). Copy the Grepr token when the **Grepr Token** dialog appears, because you need it to build the ingestion URL in Step 6.
+
+To keep one agent's sessions separate from another's, create one integration for each agent you want to report separately.
+
+### Step 2: Create the pipeline
+
+To create the pipeline, on the **Pipelines** page, click **Create pipeline**, select **Agent Sessions Pipeline** as the pipeline type, enter a name, and click **Create**.
+
+### Step 3: Add sources
+
+A source is one OpenTelemetry integration carrying one agent's events and execution spans. To add a source, on the pipeline details page, click **Sources** in the left pane, then click **Add source**. In the **Add Source** dialog:
+
+* In the **OTLP Integration** menu, select the integration you created in Step 1.
+* In the **Source Name** field, enter a name using lowercase letters, numbers, and underscores. Grepr suggests a name based on the integration you selected.
+
+Click **Add** to save the source. Grepr derives both signals from this one source, so you do not add a separate source for logs and traces.
+
+You cannot change the integration on an existing source. To point a source at a different integration, delete the source and add a new one.
+
+### Step 4: Store sessions in the data lake
+
+To choose where Grepr stores your sessions, click **Data Lake** in the left pane, then click **Add**. In the **Configure Data Lake** dialog, select a dataset from the **Dataset** menu and click **Add**. To move the pipeline to a different dataset later, click **Edit**. Grepr stores the events and execution spans for every session in this dataset, which is what makes sessions searchable in the Agent Sessions page. To learn more about how Grepr stores your data, see [_](/grepr-platform/data-lake).
+
+### Step 5: Optionally forward sessions
+
+To send sessions to another platform, click **Sinks** in the left pane and add an OpenTelemetry integration. Grepr forwards a session's events to the integration's OTLP logs endpoint and its execution spans to the traces endpoint, so the destination must accept both. A pipeline that only stores sessions in the data lake needs no sinks.
+
+### Step 6: Configure your agent to send telemetry
+
+Configure your agent to export OTLP to the ingestion URL for the integration you added as a source. For the settings each supported harness requires, select the tab for your agent in the [configuration examples for sending data to Grepr](/integrations/open-telemetry#configure-forwarding-to-grepr).
+
+How many signals a harness needs depends on the harness. Claude Code and Codex report part of a session on their log events and part on their spans, so configuring either for a single signal produces an incomplete session. OpenCode reports a whole session on its spans, so it needs traces alone.
+
+## Explore agent sessions \[#explorer]
+
+To read the sessions your pipeline captured, in the **Agent Sessions** menu, select the dataset you configured in Step 4. Set a time range and run a search to list the sessions active in that range.
+
+The sessions list reports one row per session, with the time it started, the earliest prompt in the range, the emitter, the identity that ran it, the model, the number of tool calls, the duration, and the number of errors. Because the widest column is the earliest prompt, you can scan the list for the session you want by what it was asked to do. To narrow the list, enter a query in the search field. A session matches when any of its content matches, and the **Matched content** column shows which part matched.
+
+### Filter the sessions list \[#filter-sessions]
+
+The search field takes the same Datadog-like syntax as Log Explorer, so a bare word searches the content of a session. To learn more about the syntax, see [_](/queries/datadog).
+
+Grepr also tags every event it stores for a session, and you can filter on those tags:
+
+| Tag | What it holds |
+| --- | --- |
+| `agent_emitter` | The harness that produced the session, such as `claude-code`. |
+| `agent_session_id` | The session's identifier, which is the value shown in the session header. |
+| `agent_event_kind` | The kind of event, such as `tool_call`. |
+| `agent_turn_id` | The turn the event belongs to. |
+
+For example:
+
+```text
+agent_emitter:claude-code
+
+agent_emitter:codex agent_event_kind:tool_call
+
+agent_session_id:8c1d4a02-5e7b-4f19-9a30-b6e2c4d80f55
+```
+
+The kinds a session records go beyond the five that make up a transcript, and which kind carries a given fact depends on the harness. A tool result Grepr captured only as metadata is stored as `tool_result_metadata` rather than `tool_result`, which is what a Claude Code session captured without spans records. To see the kinds a session actually stored, open it and read **Raw events**.
+
+Grepr searches a session's events rather than the session as a whole, so a session matches when any one of its events matches. Filtering on a kind therefore selects the sessions that recorded that kind of event, and each matching session still opens on its full transcript. Combining terms narrows the list, because Grepr applies them together.
+
+Select a session to open it. A session opens on the following views:
+
+* The **Transcript** view reads the session as a conversation, one card per turn, with each model call, tool call, and tool result nested under the turn that produced it. Use **Collapse all** to scan a long session by turn, and expand a turn to read its content.
+* The **Timing waterfall** view charts the session's execution spans, so you can see how long each model call and tool execution took and which steps overlapped. This view appears only when the session has execution spans.
+
+Above the transcript, a summary bar reports the session's shape and what it consumed: turns, tool calls, errors, duration, token counts, and cost. Every error in the session is listed above the transcript as well, each one joined back to its tool call, so you do not have to search a long transcript to find what failed. **Raw events** lists every event Grepr stored for the session, which is where you confirm what a harness actually sent when a transcript looks incomplete.
+
+The timing waterfall charts the same session as a span tree, so a step that dominated the run is visible without reading the transcript.
+
+## Analyze many sessions at once \[#analytics]
+
+Reading one session tells you what one run did. To find the patterns across many runs, run an analysis over a set of sessions. An analysis reads the sessions your search selected, groups them by what you asked the agent to do, labels each group, and reports what each group consumed.
+
+Grepr groups sessions by meaning rather than by matching text, so two sessions that asked for the same thing in different words land in the same group. A session that fits no group is counted as *miscellaneous* rather than forced into one it does not belong to.
+
+### Start an analysis \[#start-analysis]
+
+To start an analysis, on the **Agent Sessions** page, run the search that selects the sessions you want, then click **Analyze**. In the **Analyze agent sessions** dialog:
+
+* In the **Session cap** field, set the maximum number of sessions to analyze. The default is `10000` and the maximum is `100000`.
+* In the **Maximum named groups** field, set how many groups the analysis labels. The default is `20` and the maximum is `100`.
+* In the **Model integration** menu, select the OpenAI or Gemini integration that Grepr uses to group and label the sessions.
+
+An analysis covers a time range of at most 31 days, and it analyzes the sessions from the search you last submitted. Because an analysis calls the model integration you select, it consumes tokens on that integration.
+
+Grepr runs the analysis in the background. To read the reports it produces, click **Analytics**.
+
+### Read a report \[#read-report]
+
+The **Analytics** view lists one row per report, with the report identifier, when it was created, the query and time range it covers, its status, and how many sessions it analyzed and groups it found. Expand a row to see how the analysis ran: the session cap and group limit it used, how many sessions matched and were analyzed, how many groups were named against how many sessions were left as miscellaneous, the embedding and labeling models, and any warnings.
+
+To open the visualizations for a report, in the row's actions menu, click **Visualize**.
+
+A dashboard opens on a row of totals for the sessions it analyzed: how many sessions and intent groups it found, input and output tokens with reasoning and cache reads broken out, tool calls and how many of them failed, the cost the harnesses reported, and the total session duration with the number of model calls behind it. Below the totals, two charts rank the intents by number of sessions and the tools by number of calls, so you can see what your agents are most often asked to do and which tools carry that work. Each intent carries the description the labeling model wrote for it. Use the **Top results** menu to change how many rows each chart shows.
+
+### Compare intents against tools and models \[#report-breakdowns]
+
+The **Intent and tool overlap** table reports how many sessions in each intent used each tool, shading each cell by magnitude, which is where a tool that only one kind of work depends on becomes visible.
+
+The **Token usage** tables break the same reported usage down by model, by emitter, by intent, and by agent role, so you can attribute spend to the work that caused it rather than to the harness as a whole. An asterisk marks a total whose reported cost is only partial, because not every harness reports cost.
+
+The dashboard charts summaries that Grepr computes when the analysis runs, not the sessions themselves. To work with the sessions individually, in the row's actions menu, click **Download report** and analyze the CSV.
+
+## Troubleshoot agent session capture \[#troubleshooting]
+
+An agent that is exporting telemetry successfully can still produce no sessions, because the data reaching Grepr is the wrong shape rather than absent. Check the following before investigating the pipeline.
+
+**Sessions appear but have no timing waterfall.** The harness is exporting log events but not spans. Claude Code exports spans only when you set `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` alongside a traces exporter. Codex uses a separate `otel.trace_exporter` setting for spans, and configuring only `otel.exporter` sends log events alone. In both cases the agent reports no error, because each harness is doing exactly what you configured.
+
+**A transcript shows metadata but no prompts, responses, or tool results.** Content logging is off. Claude Code and Codex redact content by default, so you must turn it on explicitly. For the settings each one uses, see the tab for your agent in the [configuration examples for sending data to Grepr](/integrations/open-telemetry#configure-forwarding-to-grepr). OpenCode's plugin reports content without a separate setting, so an OpenCode session missing content points at the plugin instead.
+
+**Data arrives in the data lake but no sessions appear.** Grepr received telemetry it does not recognize as agent activity. The most common causes are an overridden `OTEL_SERVICE_NAME`, which stops Grepr identifying the harness, and, for OpenCode, a missing OpenTelemetry plugin. Without the plugin, OpenCode's built-in instrumentation reports internal runtime operations such as `sql.execute` instead of agent activity, and that data is stored without being assembled into a session.
+
+**A session names content its harness never sent.** This is expected for some harnesses and is not a configuration error. Codex reports no assistant text at all, so its sessions show the note that the emitter does not report assistant responses. Claude Code reports tool output only on a span event, so a session captured without spans records the size of each tool result rather than its content.

package/build/dist/docs-index/168522ae-790a-4f75-aef7-637d2b9ae22d.txt

@@ -0,0 +1,27 @@
+# TrinoAnalyticsSource
+
+**Type**: `object`
+
+## Properties
+
+- name: name (required)
+  type: string
+
+- name: query (required)
+  type: `AnalyticsQuery`
+
+- name: queryEngineIntegrationId (required)
+  type: string
+  description: Trino query engine integration to execute this query against.
+
+- name: scanBudgetBytes (optional)
+  type: integer
+  description: Maximum number of bytes this query may process.
+
+- name: tables (required)
+  type: array of `AnalyticsTableBinding`
+  description: Dataset tables available to the query under logical aliases.
+
+- name: type (required)
+  type: enum: `trino-analytics-source`
+  description: Executes an analytical query using a Trino query engine.

package/build/dist/docs-index/1ba4abb3-9709-4252-84b0-37c06efac5ae.txt

@@ -0,0 +1,15 @@
+# AnalyticsVocabularyResponse
+
+**Type**: `object`
+
+## Properties
+
+- name: fields (required)
+  type: array of `AnalyticsField`
+
+- name: functions (required)
+  type: array of `AnalyticsFunction`
+
+- name: promotedTagKeys (optional)
+  type: array of string
+  description: Promoted logs_raw tag keys for the requested dataset.

package/build/dist/docs-index/2079e858-7ce0-4d43-9f40-a321bfe4c921.txt

@@ -0,0 +1,95 @@
+Aggregate logs in the Grepr data lake with Analyze mode, using Grepr SQL expressions over log fields, tags, and parsed attributes.
+
+# Aggregate logs with Analyze mode
+
+Log Explorer's Analyze mode groups and aggregates the logs your search returns instead of listing them. You describe the analysis as a set of Grepr SQL expressions, and Grepr runs it against the logs in the data lake.
+
+## Create an analysis
+
+1. Go to Log Explorer and select a dataset and a time range.
+2. Enter a search query to filter the logs you want to analyze. Analyze mode accepts the same [Datadog-like syntax](/queries/datadog) and [New Relic log query-like syntax](/queries/new-relic) as searching.
+3. Open the menu on the **Search** button and select **Analyze**.
+4. Enter one or more expressions for the values to compute, and give each one a name. A value you don't name is named for you, after the field or function it computes.
+5. To group the results, enter the expressions whose distinct combinations you want as rows. Without a grouping expression, the analysis returns one row for the whole time range.
+6. To keep only some of the groups, enter a condition over the computed aggregates.
+7. To sort the results, enter the expressions to sort by and select ascending or descending for each one.
+8. Set the maximum number of rows to return. An analysis returns 2,500 rows by default, and Log Explorer accepts a limit of up to 10,000 rows.
+
+Grouping and sorting expressions can refer to a computed value by the name you gave it.
+
+## Log fields
+
+Expressions address the stored log columns by the following names:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `message` | VARCHAR | The log line. |
+| `severity` | INTEGER | The numeric severity level, where a higher number is more severe. |
+| `event_timestamp` | TIMESTAMP | When the event happened. |
+| `received_timestamp` | TIMESTAMP | When Grepr received the event. |
+| `id` | VARCHAR | The identifier of the event. |
+| `tags` | MAP | The tag values, keyed by tag name. |
+| `attributes` | VARIANT | The whole parsed attribute document. |
+
+> These are the Grepr SQL column names, which use `snake_case`. They are not the camelCase field names of the log event JSON that the search and export APIs return.
+
+A tag holds an array of values, so index the value you want:
+
+```sql
+tags['service'][1]
+```
+
+Address an attribute with the `@` form, which accepts dotted paths:
+
+```sql
+@http.status_code
+```
+
+## Expressions
+
+Expressions are Grepr SQL, so aggregates, `CASE`, `CAST`, and the scalar functions Grepr SQL supports are all available. Log Explorer suggests the functions your dataset accepts as you type. To learn more, see [SQL functions](/transforms/sql-transform/sql-functions).
+
+```sql
+-- Log count by service: one computed value, one grouping expression
+COUNT(*)
+tags['service'][1]
+
+-- 95th percentile request duration by endpoint
+APPROX_PERCENTILE(@duration_ms, 0.95)
+@http.route
+
+-- Severity buckets
+CASE WHEN severity >= 4 THEN 'error' ELSE 'ok' END
+```
+
+An attribute has no declared type, so Grepr infers its type from how you use it. `SUM(@duration_ms)` reads the attribute as a number, and `LOWER(@user)` reads it as a string. Cast the attribute when you need a specific type or precision:
+
+```sql
+CAST(@duration_ms AS BIGINT)
+MIN(CAST(@duration_ms AS DOUBLE))
+```
+
+## Results
+
+Each result row is a JSON object keyed by column name, so a column holds whatever the underlying attribute held, such as a number, a string, a boolean, or a nested object. Timestamps are returned as UTC ISO 8601 strings.
+
+## Limitations
+
+* An analysis reads one dataset at a time. Joins across datasets are not supported.
+* Sorting by an attribute that you have not cast sorts it by its stored text, so `100` sorts before `99`. Cast the attribute to sort numerically, as in `CAST(@http.status_code AS BIGINT)`.
+* An analysis can compute at most 128 values, group by at most 64 expressions, and sort by at most 64 expressions. Each expression can be at most 4,096 characters long.
+* Row, array, and map values are converted to nested JSON automatically. A column is rejected with an error that names it only if its value type has no JSON representation at all, or a constructed row has two fields with the same name.
+
+## Frequently Asked Questions
+
+### How do I aggregate logs in Grepr?
+
+Go to Log Explorer, select a dataset and time range, enter a search query, then select Analyze from the menu on the Search button. Enter Grepr SQL expressions for the values to compute, the expressions to group by, and the sort order.
+
+### What are the log field names in Grepr SQL?
+
+message, severity, event_timestamp, received_timestamp, id, tags, and attributes. Index a tag as tags\['service']\[1], and address an attribute as @http.status_code.
+
+### How many rows can an analysis return?
+
+An analysis returns 2,500 rows by default. Log Explorer accepts a limit of up to 10,000 rows.

package/build/dist/docs-index/{ee8aea44-9303-4734-9fea-680e4f2ba840.txt → 20f5e5b9-4685-4327-b43b-097606357df1.txt}

@@ -21,6 +21,9 @@ This schema accepts one of the following types:
 `MetricData`
 
 ### Option 5
+`VariantEvent`
+
+### Option 6
 `AgentSessionSummary`
 
 ## Properties

package/build/dist/docs-index/{4c7aa72c-18cf-4daf-9601-68b71c18e2bc.txt → 2158a228-e5ca-492c-ae16-48f90a209f09.txt}

@@ -1,5 +1,7 @@
 # EventPredicate
 
+Predicate applied to rows before analytical aggregation.
+
 **Type**: `object`
 
 ## One Of

package/build/dist/docs-index/264755b1-bf84-4b14-a34b-7e8f632b901a.txt

@@ -0,0 +1,17 @@
+# AnalyticsQuery
+
+Complete analytical query to execute.
+
+**Type**: `object`
+
+## One Of
+
+This schema accepts one of the following types:
+
+### Option 1
+`StructuredAnalyticsQuery`
+
+## Properties
+
+- name: type (required)
+  type: string

package/build/dist/docs-index/3b86009b-80ce-4c24-9379-53f74e9ec006.txt

@@ -0,0 +1,26 @@
+# Get analytics expression vocabulary
+
+**GET** `/v1/query/analytics-vocabulary`
+
+**Operation ID**: `getAnalyticsVocabulary`
+**Summary**: Get analytics expression vocabulary
+Returns parser-approved expression functions and logical log fields. With a dataset, includes that dataset's promoted logs_raw tag keys.
+
+## Tags
+- Query Parsing
+## Parameters
+
+- **datasetId** (optional) - query
+  - Dataset whose promoted logs_raw tags should be included.
+  - Type: string
+
+## Responses
+
+### 200
+
+Analytics vocabulary returned successfully.
+
+- **Content-Type**: `application/json` / `AnalyticsVocabularyResponse`
+### 401
+
+Unauthorized

package/build/dist/docs-index/46873608-fddb-4f7a-a4e1-081b98259216.txt

@@ -0,0 +1,15 @@
+# AnalyticsField
+
+**Type**: `object`
+
+## Properties
+
+- name: accessorTemplate (optional)
+  type: string
+  description: Format string for a nested key accessor, when applicable.
+
+- name: name (required)
+  type: string
+
+- name: type (required)
+  type: string

package/build/dist/docs-index/5e107af4-db6f-4fa3-a9a9-b6c34ced936f.txt

@@ -0,0 +1,19 @@
+# AnalyticsCompletion
+
+User-facing completion templates for this function.
+
+**Type**: `object`
+
+## Properties
+
+- name: caretFromEnd (optional)
+  type: integer
+
+- name: detail (optional)
+  type: string
+
+- name: insert (optional)
+  type: string
+
+- name: label (optional)
+  type: string

package/build/dist/docs-index/660b4418-59ce-4f99-b9e6-056c8927f622.txt

@@ -0,0 +1,31 @@
+# AnalyticsFunction
+
+**Type**: `object`
+
+## Properties
+
+- name: aggregate (optional)
+  type: boolean
+
+- name: category (optional)
+  type: string
+  description: Function family used to group completions.
+
+- name: completions (optional)
+  type: array of `AnalyticsCompletion`
+  description: User-facing completion templates for this function.
+
+- name: help (required)
+  type: string
+  description: Short user-facing explanation shown with completions.
+
+- name: maxArgs (optional)
+  type: integer
+  description: Null for variadic functions.
+
+- name: minArgs (optional)
+  type: integer
+  description: Null for variadic functions.
+
+- name: name (required)
+  type: string

package/build/dist/docs-index/72b41129-9835-4c64-af7a-34f6b574a02f.txt

@@ -0,0 +1,44 @@
+# StructuredAnalyticsQuery
+
+**Type**: `object`
+
+## Properties
+
+- name: end (required)
+  type: string
+  description: End of the time interval to query.
+
+- name: from (required)
+  type: string
+  description: Logical table alias to query.
+
+- name: groupBy (optional)
+  type: array of string
+  description: Grepr SQL expressions or projection aliases used for grouping.
+
+- name: having (optional)
+  type: string
+  description: Optional Grepr SQL expression applied after aggregation.
+
+- name: limit (optional)
+  type: integer
+  description: Maximum number of result rows.
+
+- name: orderBy (optional)
+  type: array of `AnalyticsOrderBy`
+  description: Ordering applied to the analytical results.
+
+- name: predicate (required)
+  type: `EventPredicate`
+
+- name: select (required)
+  type: array of `AnalyticsProjection`
+  description: Expressions returned by the query.
+
+- name: start (required)
+  type: string
+  description: Start of the time interval to query.
+
+- name: variables (optional)
+  type: object
+  description: Variables available while parsing the predicate.

package/build/dist/docs-index/{6f1eb12a-4604-42c0-a404-77dbd2de0054.txt → 8343bb9f-bf53-4858-929e-154328a4b5a7.txt}

@@ -8,4 +8,8 @@ An example of a pipeline is a log or trace reduction pipeline that reduces the v
 
 ## 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).
+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).
+
+## 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/{291213f5-c437-459e-913a-1ce5e2355bc6.txt → 83a455cd-4b36-4820-ba74-3ba29d202d22.txt}

@@ -90,9 +90,11 @@ To use the PrivateLink endpoint service, insert `.private` after the `ingest` ho
 
 Although all sources created from the same integration share the same ingestion URL, you can use a single integration to create sources for multiple pipelines. The Grepr platform ensures events are routed to the correct pipelines.
 
-Replace `<grepr-token>` with the token generated when you created the OpenTelemetry integration in Step 1.
+Replace `<grepr-token>` with the token generated when you created the OpenTelemetry integration in Step 1. The token is part of the ingestion URL rather than a separate credential, so a collector or agent that sends to this URL needs no authentication header.
 
-To see configuration examples for sending data to Grepr, select the tab for your preferred collector:
+Some senders take the ingestion URL as it is and append the path for each signal themselves. Others need the full path for one signal. For example, if your ingestion URL is `https://YWNQbQSarRBsa-<org-id>.ingest.grepr.ai/otlp/uUasjYpMJdpQZ9cNlLEtthuXNRp6n3ND_xND80PVXNk=`, then the endpoint for log events is that URL followed by `/v1/logs`, and the endpoint for spans is the same URL followed by `/v1/traces`. Each tab below states which form its sender expects.
+
+To see configuration examples for sending data to Grepr, select the tab for your collector or coding agent:
 
 The OpenTelemetry Collector can send logs to Grepr using the `otlphttp` exporter. In the OpenTelemetry collector configuration, set the endpoint to the ingestion URL from your OpenTelemetry integration:
 
@@ -180,6 +182,107 @@ For example, if your ingestion URL is `https://YWNQbQSarRBsa-<org-id>.ingest.gre
 
 To learn more about configuration settings for Fluent Bit, see the documentation for the [Fluent Bit OpenTelemetry output plugin](https://docs.fluentbit.io/manual/data-pipeline/outputs/opentelemetry).
 
+Claude Code exports its own telemetry over OTLP. It reports prompts, assistant responses, tool calls, token counts, and cost as OTLP log events, and reports each interaction, model request, and tool execution as OTLP spans. An agent sessions pipeline reads both signals, so set a logs endpoint and a traces endpoint.
+
+* `CLAUDE_CODE_ENABLE_TELEMETRY` turns on telemetry and is required.
+* `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` turns on spans. Without it, Claude Code exports no traces, and a session has no execution spans and no timing waterfall.
+* `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_ASSISTANT_RESPONSES`, and `OTEL_LOG_TOOL_DETAILS` record prompt text, response text, and tool arguments. Without them, Claude Code redacts the content and a transcript shows metadata only.
+* `OTEL_LOG_TOOL_CONTENT` records what each tool returned. Claude Code reports tool output only on a span event, so this setting requires spans.
+* `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` and `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` each take the full path for their signal, so append `/v1/logs` and `/v1/traces` to the ingestion URL.
+* `OTEL_METRICS_EXPORTER` is set to `none` because an agent sessions pipeline reads logs and traces only.
+
+The following example exports the settings and then starts Claude Code:
+
+```bash
+export CLAUDE_CODE_ENABLE_TELEMETRY=1
+export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
+export OTEL_LOGS_EXPORTER=otlp
+export OTEL_TRACES_EXPORTER=otlp
+export OTEL_METRICS_EXPORTER=none
+export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf
+export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
+export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=<ingestion-url>/v1/logs
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=<ingestion-url>/v1/traces
+export OTEL_LOG_USER_PROMPTS=1
+export OTEL_LOG_ASSISTANT_RESPONSES=1
+export OTEL_LOG_TOOL_DETAILS=1
+export OTEL_LOG_TOOL_CONTENT=1
+
+claude
+```
+
+Replace `<ingestion-url>` with the ingestion URL from your OpenTelemetry integration.
+
+> Claude Code truncates prompts, responses, and tool content at 60 KB. Grepr labels shortened content as a truncated capture in the transcript. To raise the limit, set `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` to a larger value.
+
+To learn more about the settings Claude Code supports, see [Monitoring usage](https://code.claude.com/docs/en/monitoring-usage).
+
+To learn what an agent session contains and how to build the pipeline that captures one, see [Capture and explore agent sessions](https://docs.grepr.ai/pipelines/agent-sessions).
+
+Codex exports its own telemetry over OTLP. It reports prompts, tool results, and token counts as OTLP log events named `codex.*`, and reports turns, model responses, and command executions as OTLP spans. Codex selects a separate exporter for each signal, so configure both.
+
+* `otel.exporter` selects the exporter for log events.
+* `otel.trace_exporter` selects the exporter for spans. Without it, Codex exports no spans, and a session has no execution spans and no timing waterfall.
+* Each endpoint must include the path for its signal, `/v1/logs` for log events and `/v1/traces` for spans. Codex sends to the endpoint you configure without appending a path.
+* `otel.metrics_exporter` is set to `none` because an agent sessions pipeline reads logs and traces only. The default sends metrics to Statsig.
+* `otel.log_user_prompt` records prompt text. Without it, Codex omits the prompt and a transcript shows metadata only.
+
+The following example is a snippet from the Codex configuration file, `~/.codex/config.toml`:
+
+```ini
+[otel]
+environment = "production"
+log_user_prompt = true
+metrics_exporter = "none"
+
+[otel.exporter.otlp-http]
+endpoint = "<ingestion-url>/v1/logs"
+protocol = "binary"
+
+[otel.trace_exporter.otlp-http]
+endpoint = "<ingestion-url>/v1/traces"
+protocol = "binary"
+```
+
+Replace `<ingestion-url>` with the ingestion URL from your OpenTelemetry integration.
+
+> Codex reports a different service name for each of its binaries, `codex_exec` when you run `codex exec` and `codex_cli_rs` when you run the interactive CLI. Grepr recognizes both, so sessions from either binary appear together.
+
+To learn more about the settings Codex supports, see the [Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).
+
+To learn what an agent session contains and how to build the pipeline that captures one, see [Capture and explore agent sessions](https://docs.grepr.ai/pipelines/agent-sessions).
+
+OpenCode reports agent activity through an OpenTelemetry plugin, which exports prompts, assistant responses, tool calls, tool results, token counts, and cost as OTLP spans. Register the plugin in your OpenCode configuration and then point it at your ingestion URL.
+
+* The `plugin` array in your OpenCode configuration loads `@devtheops/opencode-plugin-otel`. Pin the version so a later release cannot change what the plugin reports.
+* `OPENCODE_ENABLE_TELEMETRY` turns on the plugin's export and is required.
+* `OPENCODE_OTLP_ENDPOINT` is the ingestion URL without a signal path. The plugin appends the path itself.
+* `OPENCODE_DISABLE_LOGS` stops the plugin exporting log records. The plugin reports a whole session on spans, so its log records are not part of an agent session.
+* Leave the standard `OTEL_` variables unset. They turn on OpenCode's built-in instrumentation, which reports internal runtime operations such as `sql.execute` rather than agent activity.
+
+The following example registers the plugin, exports the settings, and then starts OpenCode:
+
+```bash
+cat > opencode.json <<'JSON'
+{
+  "plugin": ["@devtheops/opencode-plugin-otel@1.4.0"]
+}
+JSON
+
+export OPENCODE_ENABLE_TELEMETRY=1
+export OPENCODE_OTLP_ENDPOINT=<ingestion-url>
+export OPENCODE_OTLP_PROTOCOL=http/protobuf
+export OPENCODE_DISABLE_LOGS=1
+
+opencode
+```
+
+Replace `<ingestion-url>` with the ingestion URL from your OpenTelemetry integration.
+
+> The plugin also exports metrics, which an agent sessions pipeline does not read. To stop exporting them, set `OPENCODE_DISABLE_METRICS` to a comma-separated list of the metric names you want to disable. The setting matches each name exactly and has no single value that disables all of them.
+
+To learn what an agent session contains and how to build the pipeline that captures one, see [Capture and explore agent sessions](https://docs.grepr.ai/pipelines/agent-sessions).
+
 ## Use an OTLP/HTTP compatible vendor integration in a Grepr pipeline \[#vendor-otel-configuration]
 
 The following tabs show the integration configurations required to connect Grepr to an observability vendor's OTLP/HTTP endpoint. To connect to a vendor not listed here: