From 0d7ef289b6d3d246f33d0d8da5816a9af5a8319d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 27 Aug 2026 12:07:30 +0000 Subject: [PATCH 1/3] Sync OrionIQ docs with 3 months of API and product changes Add an OrionIQ API reference and a Memory page, and correct the OrionIQ user guide against changes merged between 2026-05-27 and 2026-08-27. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016YV5STTjgrMt8UX44CVHjr --- agents.md | 76 ++++++ docs/open360/settings/ai-settings.md | 26 +- docs/user-guide/orioniq/agents-hub.md | 60 ++++- docs/user-guide/orioniq/api.md | 251 +++++++++++++++++++ docs/user-guide/orioniq/create-agent.md | 6 +- docs/user-guide/orioniq/index.md | 4 + docs/user-guide/orioniq/memory.md | 52 ++++ docs/user-guide/orioniq/usage-performance.md | 16 +- docs/user-guide/orioniq/utilities.md | 25 +- 9 files changed, 490 insertions(+), 26 deletions(-) create mode 100644 agents.md create mode 100644 docs/user-guide/orioniq/api.md create mode 100644 docs/user-guide/orioniq/memory.md diff --git a/agents.md b/agents.md new file mode 100644 index 00000000..45d9bb3e --- /dev/null +++ b/agents.md @@ -0,0 +1,76 @@ +# agents.md + +Operational memory for the OrionIQ API documentation sync bot. Maintained by the bot; read it before a run and update it after. + +## Purpose + +Scan the default branches of `logzio/Artemis`, `logzio/OIQ-AI-service`, and `logzio/gaia-hermes-ws` for changes that affect OrionIQ's public-facing surface, audit this repo against them, and open a PR with the doc updates. + +## Where the code lives + +| Repo | Default branch | What's relevant | +|---|---|---| +| `gaia-hermes-ws` | `master` | `app-ai/` — the OrionIQ backend. **`app-ai/src/routes/public.routes.ts` is the definitive list of customer-callable endpoints** (`exposedTo: ['PUBLIC_API']`, prefix `/v2`). `app-ai/src/routes/orion-iq*.routes.ts` are the browser-facing BFF (`/app-ai/*`) — not customer API, but they drive the UI the user guide describes. `app-ai/CLAUDE.md` is a high-quality, current description of endpoints, capping, and audit behavior. | +| `Artemis` | `main` | `apps/orioniq/` — the OrionIQ standalone UI. **The single best source of user-facing copy**: `constants.ts` files next to each page carry the exact labels, tooltips, and guidance text the product shows. `columns.tsx` files give the real table columns. | +| `OIQ-AI-service` | `main` | `ai_service/`, `ai_backend/` — the AI/agent runtime. Mostly internal, but features surface through app-ai (for example, lessons in `ai_backend/knowledgebase/lessons/`). Pair its commits with the gaia commit that exposes them. | + +## Canonical source for the public API + +`Artemis` → `apps/orioniq/src/pages/Agents/Components/AgentEdit/api-endpoints.ts` is the in-app API reference shown to users on the agent's **API** section, rendered by `AgentApiDocs.tsx`. Mirror it — it is product-approved wording with request and response examples. + +Caveat: it lags. As of 2026-08-27 it did not list the `lessons` endpoints that had already shipped in `public.routes.ts`. Always cross-check it against `public.routes.ts` and treat the routes file as the authority on what exists. + +Base URL and auth: `X-API-TOKEN` header; `AgentApiDocs.tsx` hardcodes `https://api.logz.io`, but this repo's convention is `<>` with a link to Account region, which is more correct across regions. + +## This repo's conventions + +* **Two parallel doc trees.** `docs/open360/*` (current nav) and `docs/user-guide/*` (legacy nav) hold near-duplicate pages that differ only in app URLs and screenshots. When editing a page, check whether a twin exists — `find docs -name ""` — and update both. +* **OrionIQ lives only under `docs/user-guide/orioniq/`.** There is no `docs/open360` OrionIQ section. Don't create one; that's a nav decision, not a doc fix. +* **Frontmatter** on every page: `sidebar_position`, `title`, `image` (the shared `docs-social.jpg`), `description`, `keywords` (array). Check for `sidebar_position` collisions inside a directory before adding a page. +* **`_category_.json`** sets a directory's label and position. +* **Admonitions:** `:::note`, `:::tip`, `:::info note`, closed with `:::`. +* **Internal links** are absolute doc paths with a trailing slash: `/docs/user-guide/orioniq/agents-hub/`. +* **Includes:** `{@include: }` works and is used ~276 times. But `docs/_include/api-cookbook/replace-vars.html` and `read-more-api-doc.html` are **dead legacy Jekyll** — they contain raw Liquid and no page uses them. Inline the "replace `<>` / `<>`" bullets instead, as `docs/user-guide/integrations/api-cookbook/who-am-i.md` does. +* **API doc style:** endpoint heading, a fenced block with method and path, a `curl` sample with `X-API-TOKEN`, then a field table and a JSON response block. +* Tables are the house style for field, column, and option lists. Prose stays short. + +## Recurring documentation patterns + +* A change to an Agents Hub or Usage & Performance column lands in an Artemis `columns.tsx`; the doc's column table needs the same row. These drift often. +* New filters land in `AgentHubFilters.tsx` plus a `*-static-options.util.ts`. The wire values are strings, never booleans. +* Capping and budget copy lives in `apps/orioniq/src/pages/Settings/components/CappingSettings/constants.ts`. Quote it rather than paraphrasing — the wording is deliberate (for example, the trial/free budget is never described as "monthly", because it doesn't reset). +* Don't document Consul-configured dollar amounts or thresholds. They're per-environment and change without a code change. +* Code comments can be stale even when the code isn't. `orion-iq-memory-docs.routes.ts` still says user docs come from an in-memory mock, months after that was replaced. Verify against the commit that changed the behavior. + +## Known gaps not yet documented + +* **OrionIQ chat** has no page in this repo. Chat renaming, the server-owned chat-mode registry (Fast / Advanced), conversation history, stopping an in-flight run, and legacy AI Assistant history all shipped in the 3 months to 2026-08-27. The blocker is scope, not evidence: the chat renders in two surfaces (the Open 360 drawer and the OrionIQ standalone app) and it isn't clear which nav path the docs should describe. Confirm with the team before writing it. +* **Mobile push notifications** for finished agent runs (ORIONIQ-1463/1464) are undocumented. +* **OrionIQ for SIEM** (ORIONIQ-622) is undocumented. +* **Agent audit log** provenance columns (ORIONIQ-1531) are undocumented; unclear whether the audit log is customer-visible. +* **User journeys** (in-product tours, ORIONIQ-1432) are undocumented and probably don't need docs. + +## Run log + +### 2026-08-27 — initial run, 3 months of history (since 2026-05-27) + +Scanned 110 commits in `OIQ-AI-service`, ~90 OrionIQ-related in `gaia-hermes-ws`, ~60 in `Artemis`. + +Public API changes found in the window: + +* `GET /v2/ai-agent/:agentId/feedback/:sessionId` — new (ORIONIQ-1011) +* `POST /v2/ai-agent/:agentId/feedback` — `comment` field added (ORIONIQ-1011) +* `GET /v2/ai-agent/:agentId/lessons` — new (ORIONIQ-1491 + ORIONIQ-1144) +* `PUT /v2/ai-agent/:agentId/lessons/:lessonId/status` — new (same) + +The rest of the `/v2` surface predates the window and had never been documented here at all, so the new `api.md` covers it whole — an endpoint delta alone couldn't stand as a page. + +Also documented: Memory (new page), Agents Hub columns/filters/capping/run outcomes/read-only role, Utilities auth methods and Logz.io API scopes, Usage & Performance tabs and cost columns. + +Corrected: `docs/open360/settings/ai-settings.md` described monthly limit inputs that no longer exist — ORIONIQ-1561 (2026-08-26) replaced that page with a card linking to the OrionIQ Platform. + +Notes for next time: + +* Clones arrive shallow (50 commits). Deepen with `git fetch --shallow-since= origin ` before scanning. +* Filtering by commit message alone over-reports. Most `feat(ai-service)` commits are internal; the ones that matter touch `public.routes.ts`, a `columns.tsx`, or a `constants.ts` with user-facing copy. +* Resolve GitHub usernames for PR assignment from a commit's `author.login` — several authors commit with a `logz.io` email that isn't their username. diff --git a/docs/open360/settings/ai-settings.md b/docs/open360/settings/ai-settings.md index a85449f0..50fa317b 100644 --- a/docs/open360/settings/ai-settings.md +++ b/docs/open360/settings/ai-settings.md @@ -1,29 +1,34 @@ --- sidebar_position: 1 title: AI Settings -description: Set monthly limits on Logz.io AI usage and review your AI subscription from Plan and usage. +description: Find and manage your account's AI usage, limits, and budget from the OrionIQ Platform. image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg keywords: [logz.io, ai settings, ai usage, ai limits, capping, plan and usage, billing, orioniq, observability] --- -AI features consume usage that's billed, so Logz.io gives you a place to cap it. **AI Settings** lives under **Settings → Plan and usage** and does two things: sets monthly limits, and shows your AI subscription details. +AI features consume usage that's billed, so Logz.io gives you a place to cap it. **AI Settings** lives under **Settings → Plan and usage**. -Find it before you roll AI features out to a team, not after. +Account-level AI settings — usage, limits, and budget configuration — are managed in the OrionIQ Platform. From the AI Settings tab, click **Configure AI settings in OrionIQ** to open them. -## Set monthly limits +Find them before you roll AI features out to a team, not after. -Two limits can be set independently, each with its own on/off toggle: +## What you can set + +In the OrionIQ Platform, the Capping page controls: | Limit | Caps | |---|---| -| **Chat** | AI chat usage | -| **Invocations** | Agent invocations | +| **Daily Invocation Limit** | Agent invocations per day across your account. System-enforced, resets at midnight UTC. | +| **Account Daily Token Limit** | AI chat tokens per day across your account. System-enforced, resets at midnight UTC. | +| **Monthly Budget** | Your AI spend for the calendar month. Configurable, resets every month. | + +Trial and free accounts have a fixed AI budget, shared by AI chat and agents, that doesn't reset, plus a daily budget that resets at midnight UTC. Neither can be edited — upgrade to a paid plan to set your own budget. -Turn a limit on and enter a monthly value; leave it off and the limit reads **No limit set**. A limit must be zero or greater — setting `0` is valid and effectively disables that kind of usage rather than being rejected as invalid. +For the full list of limits and how soft limits work, see [Capping](/docs/user-guide/orioniq/agents-hub/#capping). -Saving confirms with *AI monthly limits updated*. +## If AI is disabled -Limits are monthly, so they reset on your billing cycle rather than rolling continuously. +Your account has separate entitlements for AI chat and for agent invocations. When AI features are disabled on your account, the AI Settings tab shows a notice and AI features aren't available. Contact [Logz.io support](https://logz.io/support-page/) to enable them. :::note AI Settings is being rolled out. If you don't see it under Plan and usage, it isn't enabled for your account yet — contact [Logz.io support](https://logz.io/support-page/). @@ -32,4 +37,5 @@ AI Settings is being rolled out. If you don't see it under Plan and usage, it is ## Related * [Plan and usage](https://docs.logz.io/docs/user-guide/admin/logzio-accounts/plan-and-usage/) +* [OrionIQ](/docs/user-guide/orioniq/) * [AI Agent FAQ](/docs/open360/observability/faq/) diff --git a/docs/user-guide/orioniq/agents-hub.md b/docs/user-guide/orioniq/agents-hub.md index a422c82c..95ceff29 100644 --- a/docs/user-guide/orioniq/agents-hub.md +++ b/docs/user-guide/orioniq/agents-hub.md @@ -21,26 +21,64 @@ The **Agents** tab displays a list of all agents in your account. Each agent row | **Name** | The agent name. Click to open the agent's details. | | **Type** | The agent type (for example, Custom). | | **Triggered By** | How the agent is triggered (Scheduled, API, Deployment, or Alert). | -| **Created By** | The user who created the agent. | +| **Created By** | The user who created the agent. Agents provisioned by the platform, such as alert root cause analysis agents, are attributed to Logz.io. | | **Created At** | The date and time the agent was created. | -| **Updated At** | The date and time the agent was last modified. | +| **Updated At** | The date and time the agent was last modified. A run on its own doesn't change this. | +| **Updated By** | The user who last modified the agent. Empty when no edit has been recorded. | | **Last Run** | The date and time of the agent's most recent invocation. | | **Activation** | Toggle to enable or disable the agent. | -| **Invocation Cost** | The cost per invocation. | -| **Daily Cap** | The maximum number of invocations allowed per day. | +| **Invocation Cost** | The cost charged when this agent is triggered. | +| **Daily Cap** | Per-agent daily invocation limit, configured in each agent's settings. | | **Actions** | Additional actions available for the agent. | -You can filter agents by account using the account selector at the top of the list. - To create a new agent directly from this page, click **+ Create New Agent** in the top right corner. +### Filter the list + +Use the filters above the table to narrow the list: + +| Filter | Description | +|---|---| +| **Account** | Show agents from specific accounts. | +| **Agent Type** | Show agents of a specific type. | +| **Triggered By** | Show agents using a specific trigger. | +| **Agent Name** | Show a specific agent. | +| **Created By** | Show agents created by a specific user, or by Logz.io. | +| **Activation** | Show only agents that are **On** or only those that are **Off**. | + +The **Invocations** tab offers an **Output** filter instead of **Activation**, so you can narrow the run history to Success, Failed, or Running. + ### Capping -Click the **Capping** button to manage invocation limits across your agents. This helps you control costs and prevent agents from exceeding your usage budget. +Click the **Capping** button to manage AI spend and invocation limits across your agents. + +| Limit | Description | +|---|---| +| **Daily Invocation Limit** | System-enforced daily invocation limit across your account. Resets at midnight UTC. | +| **Account Daily Token Limit** | System-enforced daily token limit for AI chat across your account. Resets at midnight UTC. | +| **Monthly Budget** | Your configurable monthly budget. Resets every calendar month. | + +Trial and free accounts see a fixed **Budget**, shared by AI Chat and AI Agents, that doesn't reset, plus an additional **Daily Budget** that resets at midnight UTC. These limits can't be edited — upgrade to a paid plan to set your own budget. + +Limits can also carry a **soft limit**: a warning threshold that sends a notification when usage crosses it, without stopping agents from running. + +### Permissions + +Users with the Read-only role can view agents, the Agents Hub, and run history, and can use OrionIQ chat, but can't create, edit, activate, or manually trigger agents. ## Invocations tab -The **Invocations** tab displays the run history for all agents. Each row represents a single invocation and includes the agent name, type, trigger method, who created it, the execution time, and the outcome (for example, Success). +The **Invocations** tab displays the run history for all agents. Each row represents a single invocation and includes the agent name, type, trigger method, who created it, the execution time, and the outcome. + +An invocation ends in one of the following outcomes: + +| Outcome | Description | +|---|---| +| **Success** | The run completed and produced a result. | +| **Failed** | The run ended in an error. | +| **Running** | The run is still in progress. | +| **Stopped** | You stopped the run before it finished. Any steps it completed are kept. | +| **Incomplete** | The run couldn't finish — it timed out, ran out of context, or hit an internal error. The reason is shown with the output. | ![Invocations tab showing agent run history](https://dytvr9ot2sszz.cloudfront.net/logz-docs/orioniq/orioniq-invocations.png) @@ -62,9 +100,11 @@ Shows the final analysis report generated by the agent. This may include finding ## Provide feedback -After reviewing an invocation's output, you can provide feedback on the accuracy and usefulness of the agent's results. Feedback helps improve AI performance over time and gives you a way to track agent reliability. +After reviewing an invocation's output, you can rate the accuracy and usefulness of the agent's results from the **Output** tab. Once you've rated a run, you can also add a free-text comment explaining the rating, and edit it later. + +Feedback helps improve AI performance over time and gives you a way to track agent reliability. For eligible accounts, it also feeds the lessons an agent learns and applies to later runs — see [Enable or disable a lesson](/docs/user-guide/orioniq/api/#enable-or-disable-a-lesson). -You can monitor feedback scores and coverage across all your agents from the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/). +You can monitor feedback scores and coverage across all your agents from the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/), and submit or read feedback programmatically with the [OrionIQ API](/docs/user-guide/orioniq/api/). :::tip Agents with low feedback coverage are harder to evaluate. Make it a habit to rate agent results regularly so you can identify which agents need their instructions refined. diff --git a/docs/user-guide/orioniq/api.md b/docs/user-guide/orioniq/api.md new file mode 100644 index 00000000..97cac1e0 --- /dev/null +++ b/docs/user-guide/orioniq/api.md @@ -0,0 +1,251 @@ +--- +sidebar_position: 8 +title: OrionIQ API +image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg +description: Trigger OrionIQ agents, poll for results, send follow-ups, submit feedback, and manage learned lessons using the OrionIQ API. +keywords: [OrionIQ, API, agents, trigger agent, agent run, feedback, lessons, api token, automation] +--- + +Agents configured with the **API** trigger run on demand when you call the OrionIQ API. Use it to start a run from a CI pipeline, an incident workflow, or any external system, then poll for the result. + +To find an agent's ID and a ready-to-copy request for each endpoint, open the agent in the [Agents Hub](/docs/user-guide/orioniq/agents-hub/) and go to the **API** section of its configuration. + +## Authentication + +All requests must include the `x-api-token` header. + +In the code blocks below: + +* Replace `<>` with an [API token](https://app.logz.io/#/dashboard/settings/manage-tokens/api) from the account that owns the agent +* Replace `<>` with your region's base API URL. For more information, see [Account region](/docs/user-guide/admin/hosting-regions/account-region). +* Replace `<>` with the agent's ID + +A request with a missing or invalid token returns `401`. + +## Run an agent + +``` +POST /v2/ai-agent/<> +``` + +Starts a new run and returns immediately with a session ID. The run itself is asynchronous — poll for the result with [Get run status](#get-run-status). + +### Sample request + +```shell +curl -X POST \ + https://<>/v2/ai-agent/<> \ + -H 'Content-Type: application/json' \ + -H 'X-API-TOKEN: <>' \ + -d '{ + "context": { + "message": "Summarize the errors in the checkout service", + "additionalContext": "Deployment 4.12.0 rolled out at 09:00 UTC", + "timerange": { + "startTime": "2026-08-27T08:00:00Z", + "endTime": "2026-08-27T10:00:00Z" + } + } + }' +``` + +| Field | Description | +|---|---| +| `context.message` | The prompt for this run. | +| `context.additionalContext` | Optional free-text context to pass to the agent. | +| `context.timerange` | Optional `startTime` and `endTime` bounding the data the agent analyzes. | +| `context.security` | Optional list of accounts to query, each with an optional `filter` of `field` and `value`. | +| `integrations` | Optional list of integration connections the run may use. | + +Fields you send override the matching fields in the agent's saved **Payload (JSON)**. + +### Response + +```json +{ + "status": "started", + "sessionId": "" +} +``` + +A disabled agent returns `404`, unless its trigger type is Alert. When OrionIQ is temporarily shut down for maintenance, the endpoint returns `503`. + +## Get run status + +``` +GET /v2/ai-agent/<>/ +``` + +Returns the current status of a run. Poll this endpoint until the status is terminal. + +### Sample request + +```shell +curl -X GET \ + https://<>/v2/ai-agent/<>/ \ + -H 'Content-Type: application/json' \ + -H 'X-API-TOKEN: <>' +``` + +### Response + +```json +{ + "status": "done", + "message": "", + "totalSteps": 12 +} +``` + +| Status | Meaning | +|---|---| +| `loading` | The run is still in progress. Keep polling. | +| `done` | The run finished. `message` holds the agent's output. | +| `error` | The run failed. `message` holds the reason. | +| `canceled` | The run was canceled. | +| `timeout` | The request timed out before the run produced new data. Poll again. | + +`totalSteps` reports how many steps the agent has produced so far. + +## Send a follow-up + +``` +POST /v2/ai-agent/<>/ +``` + +Continues the same conversation. Allowed only after the previous turn reached a terminal status. The request body takes the same `context` object as [Run an agent](#run-an-agent), and the response returns the same session ID, which you poll with [Get run status](#get-run-status). + +```json +{ + "status": "started", + "sessionId": "" +} +``` + +## Enable or disable an agent + +``` +POST /v2/ai-agent/<>/enable +POST /v2/ai-agent/<>/disable +``` + +A disabled agent does not start new runs, whatever its trigger configuration. + +### Response + +```json +{ + "id": "", + "active": true +} +``` + +## Submit feedback + +``` +POST /v2/ai-agent/<>/feedback +``` + +Rates one or more runs. Feedback appears in the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/) and, for eligible accounts, feeds the lessons the agent learns. + +### Sample request + +```shell +curl -X POST \ + https://<>/v2/ai-agent/<>/feedback \ + -H 'Content-Type: application/json' \ + -H 'X-API-TOKEN: <>' \ + -d '[ + { + "sessionId": "", + "feedbackName": "run-quality", + "score": 100, + "comment": "Correctly identified the failing dependency." + } + ]' +``` + +| Field | Description | +|---|---| +| `sessionId` | The run to rate. | +| `feedbackName` | A name identifying the kind of feedback. | +| `score` | A number, or a boolean that is converted to `100` for `true` and `0` for `false`. | +| `comment` | Optional free-text note. Omitting it leaves an existing comment unchanged. | + +A run holds one feedback record, so submitting again for the same session updates it. + +### Response + +```json +[ + { + "id": "", + "createdAt": "", + "agentId": "", + "accountId": 12345, + "sessionId": "", + "feedbackName": "run-quality", + "score": 100, + "comment": "Correctly identified the failing dependency." + } +] +``` + +## Get feedback + +``` +GET /v2/ai-agent/<>/feedback/ +``` + +Returns the feedback record for a run, in the same shape as a single entry in the Submit feedback response. Returns `404` when the run has no feedback. + +## List learned lessons + +``` +GET /v2/ai-agent/<>/lessons +``` + +Returns the lessons the agent has learned from feedback. A lesson records a situation the agent met, the rule it derived, and why. + +### Response + +```json +{ + "lessons": [ + { + "lessonId": "", + "status": "active", + "situation": "", + "rule": "", + "whyNote": "", + "feedbackRef": "" + } + ] +} +``` + +Only `active` lessons are added to the agent's instructions on later runs. + +## Enable or disable a lesson + +``` +PUT /v2/ai-agent/<>/lessons//status +``` + +Turns a lesson on or off. Use this to retire a lesson the agent should stop applying. + +### Sample request + +```shell +curl -X PUT \ + https://<>/v2/ai-agent/<>/lessons//status \ + -H 'Content-Type: application/json' \ + -H 'X-API-TOKEN: <>' \ + -d '{"enabled": false}' +``` + +`enabled` is required and must be a boolean; anything else returns `400`. The response returns the updated lesson in the same shape as a List learned lessons entry, with `status` set to `active` or `disabled`. An unknown lesson returns `404`. + +:::note +Agents don't have to be reachable over the API to be rated. Runs started by a Scheduled, Deployment, or Alert trigger can be rated from the Agents Hub, and the same feedback and lessons endpoints apply to them. +::: diff --git a/docs/user-guide/orioniq/create-agent.md b/docs/user-guide/orioniq/create-agent.md index b11f7f9a..17f157d7 100644 --- a/docs/user-guide/orioniq/create-agent.md +++ b/docs/user-guide/orioniq/create-agent.md @@ -40,7 +40,7 @@ Switch to the **Configure** tab to set the agent's properties and behavior. |---|---| | **Agent Name** | A descriptive name for your agent. | | **Description** | A brief explanation of what the agent does. | -| **Payload (JSON)** | Optional JSON payload to pass additional parameters to the agent. | +| **Payload (JSON)** | Optional JSON payload to pass additional parameters to the agent. Fields sent on an API invocation override the matching fields here. | ### Trigger @@ -48,7 +48,7 @@ Choose how the agent will run by selecting a trigger type: | Trigger | Description | |---|---| -| **API** | The agent runs when called via the OrionIQ API. Use this for on-demand or externally triggered invocations. | +| **API** | The agent runs when called via the [OrionIQ API](/docs/user-guide/orioniq/api/). Use this for on-demand or externally triggered invocations. | | **Scheduled** | The agent runs automatically at defined intervals (for example, every 3 hours or once a day). | | **Deployment** | The agent runs automatically when a deployment event is detected. | | **Alert** | The agent runs automatically when a Logz.io alert is triggered. | @@ -73,5 +73,5 @@ Use the **Active** toggle to enable or disable the agent. When disabled, the age Once you've reviewed the agent definition and configured the settings, click **Create Agent**. The agent becomes available in the [Agents Hub](/docs/user-guide/orioniq/agents-hub/) where you can monitor its invocations and manage its settings. :::note -You can edit an agent's instructions, trigger, and notification settings at any time from the Agents Hub. +You can edit an agent's instructions, trigger, and notification settings at any time from the Agents Hub. Users with the Read-only role can't create or edit agents. ::: diff --git a/docs/user-guide/orioniq/index.md b/docs/user-guide/orioniq/index.md index 55821b92..9ce18f50 100644 --- a/docs/user-guide/orioniq/index.md +++ b/docs/user-guide/orioniq/index.md @@ -20,6 +20,10 @@ You can access OrionIQ from the left navigation menu. The OrionIQ section includ **[Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/)**: Monitor agent usage statistics, track invocation volume, review feedback trends, and evaluate overall agent performance. +**[Memory](/docs/user-guide/orioniq/memory/)**: Give OrionIQ lasting context about your environment, your services, and how you work. + +**[OrionIQ API](/docs/user-guide/orioniq/api/)**: Trigger agents from external systems, poll for results, submit feedback, and manage the lessons agents learn. + :::note OrionIQ uses AI to analyze your data. Always review agent results and check for accuracy. ::: diff --git a/docs/user-guide/orioniq/memory.md b/docs/user-guide/orioniq/memory.md new file mode 100644 index 00000000..1017dbec --- /dev/null +++ b/docs/user-guide/orioniq/memory.md @@ -0,0 +1,52 @@ +--- +sidebar_position: 7 +title: Memory +image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg +description: Give OrionIQ lasting context about your environment with account and user memory documents. +keywords: [OrionIQ, memory, context, account memory, user memory, markdown, chat] +--- + +Memory gives OrionIQ context beyond what it can learn from your telemetry and integrations — your services and their owners, your operational conventions, and how you prefer answers. OrionIQ reads memory when answering in chat, so it can prioritize what matters to you and align its answers with your environment. + +To open Memory, navigate to **OrionIQ > Memory** in the left navigation menu. + +:::note +Memory shapes OrionIQ's answers in chat. Agents don't read memory documents yet. +::: + +## Document scopes + +Each memory document has a scope that decides who can see and edit it. + +| Scope | Visibility | +|---|---| +| **Account** | Shared with your account. Everyone can view it; only admins can edit it. It shapes chat answers for all users. | +| **User** | Your file. Only you can view or edit it. It tailors your own chat answers. | + +Every account starts with a protected account document, `ACCOUNT.md`, which you can edit but not delete. Your personal document is `USER.md`. + +## The documents table + +| Column | Description | +|---|---| +| **Name** | The document name. Click to open it. | +| **Scope** | Account or User. | +| **Last updated** | When the document was last changed. | +| **Changed by** | Who last changed it. | + +## Edit a document + +Click a document to open its editor. Documents are Markdown, and each editor explains what belongs in that document: + +* **Account** — your services, dependencies, owners, business-critical systems, and operational conventions. Focus on what a new engineer needs in order to understand your environment quickly. +* **User** — your role, responsibilities, answer preferences, and personal context that helps OrionIQ understand how you work. + +Use **Show example** in the account editor to see a sample document. + +## Add a document + +Click **Add to memory** to upload existing material — runbooks, architecture docs, or onboarding notes. Uploads must be Markdown (`.md`) files of up to 1 MB. + +:::tip +Keep memory current. Update your documents as services, ownership, and processes change, so OrionIQ isn't reasoning from a stale picture of your environment. +::: diff --git a/docs/user-guide/orioniq/usage-performance.md b/docs/user-guide/orioniq/usage-performance.md index 979cac5d..59afc5e6 100644 --- a/docs/user-guide/orioniq/usage-performance.md +++ b/docs/user-guide/orioniq/usage-performance.md @@ -12,11 +12,21 @@ To access the dashboard, navigate to **OrionIQ > Usage & Performance Report** in ![Usage & Performance Dashboard](https://dytvr9ot2sszz.cloudfront.net/logz-docs/orioniq/orioniq-usage-performance.png) +## Dashboard tabs + +The dashboard has two tabs: + +- **AI Agents**: Invocation volume, feedback, and cost for your agents. +- **AI Chat**: Token usage for OrionIQ chat. + +OrionIQ chat is reported only under **AI Chat** — its invocations are excluded from the AI Agents tab so they don't skew per-agent figures. + ## Dashboard filters Use the filters at the top of the page to narrow the data displayed: - **Agent**: Select a specific agent or view data for all agents. +- **Agent Type**: Show only agents of a specific type. - **Time**: Choose a time range (for example, 30 Days) to control the reporting period. ## Invocations @@ -38,10 +48,14 @@ The summary table at the bottom of the dashboard provides a per-agent breakdown | Column | Description | |---|---| | **Name** | The agent name. | +| **Agent Type** | The agent type. | | **Invocations** | Total number of invocations during the selected period. | | **Avg. Feedback Score** | The average feedback score received across all invocations. | | **Feedback Coverage** | The percentage of invocations that received feedback. | -| **Invocation Cost** | The total cost of invocations for the agent during the selected period. | +| **Invocation Cost** | The cost charged per invocation of the agent. | +| **Total Cost ($)** | The total cost of the agent's invocations during the selected period. | + +Invocations whose agent no longer exists — for example, a deleted agent — are grouped under **Unknown Agent**, one row per agent type, so the totals stay complete. :::tip Regularly review the Usage & Performance Dashboard to identify agents with low feedback coverage. Providing feedback on agent results helps improve AI performance and ensures your agents deliver reliable analysis. diff --git a/docs/user-guide/orioniq/utilities.md b/docs/user-guide/orioniq/utilities.md index 4e7e0659..11f53ac6 100644 --- a/docs/user-guide/orioniq/utilities.md +++ b/docs/user-guide/orioniq/utilities.md @@ -35,9 +35,30 @@ Use the search bar to find a specific utility, or click a category tab to filter ## Connect a utility -The Logz.io utility is connected by default and provides agents with access to your observability data via the Logz.io API. +Click **Connect** on a utility and choose an authentication method. Which methods a utility offers depends on the utility: -To request access to additional utilities, click **Add to Wish List** on the utility you're interested in. This helps Logz.io prioritize which integrations to support next. +| Method | Description | +|---|---| +| **OAuth 2.0** | Authorize Logz.io through the provider's own consent flow. | +| **API Key** | Connect using the provider's API token. | +| **Basic Auth** | Connect with an email address and API token. | + +## Logz.io API access + +The Logz.io utility is connected by default and gives agents access to your observability data. You can also grant agents scoped access to the Logz.io public API, per account: + +| Scope | Grants | +|---|---| +| **Telemetry** | Logs and metrics access for the agent. Always on for every accessible account and not configurable. | +| **Read** | The agent can call the Logz.io public API but can't change anything. | +| **Write** | The agent can create and update Logz.io objects. Implies Read. | +| **Admin** | The agent has the same role as Manage API Tokens. Implies Read and Write. | + +Enabling API access creates one system-generated API token per selected account, at the highest scope you chose. Changing or turning off API access deletes that token; agents keep their telemetry access, and a lower scope gets a new token at that scope. + +Owner, sub-accounts, and Security accounts have a public API. Metrics, Timeless, and Restored accounts do not, so API scopes aren't available for them. + +To request access to a utility that isn't yet available, click **Add to Wish List** on the utility you're interested in. This helps Logz.io prioritize which integrations to support next. :::note Utilities is an evolving capability. New integrations are added regularly based on user demand. From c529e1b664951963dbb84038351f9a08c17c009f Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 27 Aug 2026 15:10:00 +0000 Subject: [PATCH 2/3] Address review feedback on OrionIQ docs sync Rename Utilities to Integrations, correct the catalog and auth data from oiq-resources, add the Management, Settings, and Triggers surfaces, drop the lessons endpoints that aren't surfaced in the product, and fix the alert and SIEM security rule AI Analysis sections. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016YV5STTjgrMt8UX44CVHjr --- agents.md | 44 +++++++- .../alerts/configure-alerts-explore.md | 6 +- docs/open360/settings/ai-settings.md | 20 +--- .../security-rules/manage-security-rules.md | 18 ++++ .../configure-alerts-explore.md | 17 ++- docs/user-guide/orioniq/agents-hub.md | 46 +++++--- docs/user-guide/orioniq/api.md | 59 ++-------- docs/user-guide/orioniq/create-agent.md | 38 +++++-- docs/user-guide/orioniq/index.md | 6 +- docs/user-guide/orioniq/integrations.md | 102 ++++++++++++++++++ docs/user-guide/orioniq/settings.md | 53 +++++++++ docs/user-guide/orioniq/utilities.md | 65 ----------- static/_redirects | 4 + 13 files changed, 310 insertions(+), 168 deletions(-) create mode 100644 docs/user-guide/orioniq/integrations.md create mode 100644 docs/user-guide/orioniq/settings.md delete mode 100644 docs/user-guide/orioniq/utilities.md diff --git a/agents.md b/agents.md index 45d9bb3e..53ddf721 100644 --- a/agents.md +++ b/agents.md @@ -4,15 +4,16 @@ Operational memory for the OrionIQ API documentation sync bot. Maintained by the ## Purpose -Scan the default branches of `logzio/Artemis`, `logzio/OIQ-AI-service`, and `logzio/gaia-hermes-ws` for changes that affect OrionIQ's public-facing surface, audit this repo against them, and open a PR with the doc updates. +Scan the default branches of `logzio/Artemis`, `logzio/OIQ-AI-service`, `logzio/gaia-hermes-ws`, and `logzio/oiq-resources` for changes that affect OrionIQ's public-facing surface, audit this repo against them, and open a PR with the doc updates. ## Where the code lives | Repo | Default branch | What's relevant | |---|---|---| -| `gaia-hermes-ws` | `master` | `app-ai/` — the OrionIQ backend. **`app-ai/src/routes/public.routes.ts` is the definitive list of customer-callable endpoints** (`exposedTo: ['PUBLIC_API']`, prefix `/v2`). `app-ai/src/routes/orion-iq*.routes.ts` are the browser-facing BFF (`/app-ai/*`) — not customer API, but they drive the UI the user guide describes. `app-ai/CLAUDE.md` is a high-quality, current description of endpoints, capping, and audit behavior. | -| `Artemis` | `main` | `apps/orioniq/` — the OrionIQ standalone UI. **The single best source of user-facing copy**: `constants.ts` files next to each page carry the exact labels, tooltips, and guidance text the product shows. `columns.tsx` files give the real table columns. | +| `gaia-hermes-ws` | `master` | `app-ai/` — the OrionIQ backend. **`app-ai/src/routes/public.routes.ts` is the definitive list of customer-callable endpoints** (`exposedTo: ['PUBLIC_API']`, prefix `/v2`). `app-ai/src/routes/orion-iq*.routes.ts` are the browser-facing BFF (`/app-ai/*`) — not customer API, but they drive the UI the user guide describes. `app-ai/CLAUDE.md` is a high-quality, current description of endpoints, capping, and audit behavior. Alert and SIEM-rule AI Analysis live in `app-ui/src/pages/Alerts/AlertForm/.../AIAgentRCA/` — the SIEM rule form reuses the same stepper (`modelName="rule"`), so a change there hits both products. | +| `Artemis` | `main` | `apps/orioniq/` — the OrionIQ standalone UI. **The single best source of user-facing copy**: `constants.ts` files next to each page carry the exact labels, tooltips, and guidance text the product shows. `columns.tsx` files give the real table columns. `src/constants.ts` `ORIONIQ_NAV_ITEMS` is the authoritative nav — check page names against it before writing a nav path. | | `OIQ-AI-service` | `main` | `ai_service/`, `ai_backend/` — the AI/agent runtime. Mostly internal, but features surface through app-ai (for example, lessons in `ai_backend/knowledgebase/lessons/`). Pair its commits with the gaia commit that exposes them. | +| `oiq-resources` | `main` | **The catalog data, and the only correct source for it.** `integrations/*.json` — one file per integration (646 as of 2026-08), each with `name`, `categories`, `auth`, `popularityRank`; `integrations/skills/` holds their query skills. `marketplace/templates/*.json` — the live agent templates (5 shipping, plus a `future/` folder that is NOT live), each with `agentType` and `display.category`. Never hand-write a category list or an integration name — derive it from these files. | ## Canonical source for the public API @@ -34,6 +35,23 @@ Base URL and auth: `X-API-TOKEN` header; `AgentApiDocs.tsx` hardcodes `https://a * **API doc style:** endpoint heading, a fenced block with method and path, a `curl` sample with `X-API-TOKEN`, then a field table and a JSON response block. * Tables are the house style for field, column, and option lists. Prose stays short. +## Product vocabulary + +Match the product's own words, not an older doc's: + +| Say | Not | +|---|---| +| Integrations | Utilities | +| Build an Agent (the button) | + Create New Agent | +| Agents / Invocations (the Agents Hub tabs) | — | +| Alert AI Analysis (the alert and rule step) | — | + +## Open question for the docs team + +`docs/open360/observability/` and `docs/user-guide/observability/` are the SAME three pages twice — the "Observability IQ" category at both `/docs/category/observability-iq/` and `/docs/category/observability-iq-1/`, holding `assistantiq.md` (AI Agent), `ai-agent-analysis.md`, and `faq.md`. Their content also overlaps the OrionIQ pages. + +Consolidating or deleting them is a **migration, not a cleanup**: 20 inbound links across 14+ pages point at them, and `onBrokenLinks: 'throw'` means every one has to be repointed, with `static/_redirects` entries for the public URLs. Don't do it as a side effect of a sync run — it needs a decision on which tree survives. + ## Recurring documentation patterns * A change to an Agents Hub or Usage & Performance column lands in an Artemis `columns.tsx`; the doc's column table needs the same row. These drift often. @@ -41,6 +59,16 @@ Base URL and auth: `X-API-TOKEN` header; `AgentApiDocs.tsx` hardcodes `https://a * Capping and budget copy lives in `apps/orioniq/src/pages/Settings/components/CappingSettings/constants.ts`. Quote it rather than paraphrasing — the wording is deliberate (for example, the trial/free budget is never described as "monthly", because it doesn't reset). * Don't document Consul-configured dollar amounts or thresholds. They're per-environment and change without a code change. * Code comments can be stale even when the code isn't. `orion-iq-memory-docs.routes.ts` still says user docs come from an in-memory mock, months after that was replaced. Verify against the commit that changed the behavior. +* **Renaming a page needs a redirect.** Add it to `static/_redirects` **above** the trailing `/:splat` catch-all — Netlify matches in order, so a rule after it never fires. +* A page's twin can have drifted. The two `configure-alerts-explore.md` copies had different sections before this run, not just different URLs — diff them rather than assuming they match. +* Auth methods, categories, and integration names are catalog data. As of 2026-08 the catalog has **no OAuth integrations at all** (580 `apiKey`, 56 `basicAuth`, 6 keyless) — so don't document an auth method just because the UI has a code path for it. + +## Shipped in code but NOT in the product — do not document + +An endpoint existing in `public.routes.ts` is not proof a feature is available to customers. Check for a UI before documenting it, and when in doubt ask the feature's owner. + +* **Agent lessons** (`GET /v2/ai-agent/:agentId/lessons`, `PUT .../lessons/:lessonId/status`, ORIONIQ-1491 / ORIONIQ-1144). The endpoints are live and the backend learns from feedback, but there is **no lessons UI anywhere** in `Artemis` or `app-ui`, and rollout is gated per account. Documented in the first run and removed on review. Document it when the UI lands. +* The in-app API reference (`Artemis` `apps/orioniq/.../AgentEdit/api-endpoints.ts`) is a good signal here: it lists what the product actually exposes, and it did **not** list the lessons endpoints. ## Known gaps not yet documented @@ -74,3 +102,13 @@ Notes for next time: * Clones arrive shallow (50 commits). Deepen with `git fetch --shallow-since= origin ` before scanning. * Filtering by commit message alone over-reports. Most `feat(ai-service)` commits are internal; the ones that matter touch `public.routes.ts`, a `columns.tsx`, or a `constants.ts` with user-facing copy. * Resolve GitHub usernames for PR assignment from a commit's `author.login` — several authors commit with a `logz.io` email that isn't their username. + +### 2026-08-27 — review round on PR #960 + +13 review comments. What they were actually about, so the next run doesn't repeat them: + +* **Invented content.** The pre-existing Integrations category list was wrong in every row — the real 16 categories are in `oiq-resources`. Same class of error for auth methods. Lesson: never carry forward an existing doc's factual list without checking it against source; the bot inherited these and left them. +* **Wrong vocabulary.** "Utilities" is not a product word. Read `ORIONIQ_NAV_ITEMS` first. +* **Documenting the unreleased.** See the lessons section above. +* **Missing surfaces.** The Triggers menu, the Management tab, the Settings page, and most of the agent editor were all shipped and undocumented. A commit-history scan will not find these — they predate the window. Walk the product's nav and tabs against the doc tree once per run, not just the diff. +* **Two pages the scan missed entirely** because they live outside `docs/user-guide/orioniq/`: the alert AI Analysis section (whose Slack-endpoint requirement ORIONIQ-1298 had made obsolete) and the SIEM security rules page, which never documented Alert AI Analysis at all. Grep the whole `docs/` tree for AI surfaces, not just the OrionIQ directory. diff --git a/docs/open360/alerts/configure-alerts-explore.md b/docs/open360/alerts/configure-alerts-explore.md index ce85d9dc..95d72fe6 100644 --- a/docs/open360/alerts/configure-alerts-explore.md +++ b/docs/open360/alerts/configure-alerts-explore.md @@ -195,7 +195,7 @@ The system combines the **Trigger if** time interval with the **Wait time** inte ### Activate AI Agent Analysis :::note -To use AI Agent Analysis, your alert must include a **Slack notification endpoint** and a **clear description**. +Give the alert a **clear description**. That description is the context the AI uses, so a vague one produces a vague analysis. ::: [AI Agent Analysis](/docs/user-guide/observability/ai-agent-analysis/) enables Logz.io’s AI Agent to automatically investigate the cause of an alert the moment it’s triggered—delivering fast, actionable insights to help you understand what happened and why. @@ -206,13 +206,13 @@ To enable it: ![AI Analysis](https://dytvr9ot2sszz.cloudfront.net/logz-docs/alerts/ai-agent-analysis-checked.png) -* Click **Configure endpoint** and select the Slack channel where the report should be delivered. +* Choose who receives the analysis — see [Recipients for the analysis](#recipients-for-the-analysis) below. ![notification endpoint](https://dytvr9ot2sszz.cloudfront.net/logz-docs/alerts/notification-endpoint.png) * Add a clear description to your alert—this gives the AI the context it needs to produce accurate and helpful results. -Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings will be sent to your selected **Slack channel** and stored in the **AI Agent chat history** for future reference. +Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings is sent to the recipients you chose and stored in the **AI Agent chat history** for future reference. Each run also appears in the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/), where you can read its full analysis and rate it. :::caution note AI Agent Analysis runs **once every hour**. diff --git a/docs/open360/settings/ai-settings.md b/docs/open360/settings/ai-settings.md index 50fa317b..87db201a 100644 --- a/docs/open360/settings/ai-settings.md +++ b/docs/open360/settings/ai-settings.md @@ -6,25 +6,13 @@ image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social. keywords: [logz.io, ai settings, ai usage, ai limits, capping, plan and usage, billing, orioniq, observability] --- -AI features consume usage that's billed, so Logz.io gives you a place to cap it. **AI Settings** lives under **Settings → Plan and usage**. +AI features consume usage that's billed, so Logz.io gives you a place to cap it. -Account-level AI settings — usage, limits, and budget configuration — are managed in the OrionIQ Platform. From the AI Settings tab, click **Configure AI settings in OrionIQ** to open them. +Account-level AI settings — usage, limits, and budget configuration — are managed in the OrionIQ Platform, on its **Capping** page: see [OrionIQ Settings → Capping](/docs/user-guide/orioniq/settings/#capping) for the limits you can set and how soft limits work. -Find them before you roll AI features out to a team, not after. +The **AI Settings** tab under **Settings → Plan and usage** links to the same place, so you can get there from the Logz.io console too. -## What you can set - -In the OrionIQ Platform, the Capping page controls: - -| Limit | Caps | -|---|---| -| **Daily Invocation Limit** | Agent invocations per day across your account. System-enforced, resets at midnight UTC. | -| **Account Daily Token Limit** | AI chat tokens per day across your account. System-enforced, resets at midnight UTC. | -| **Monthly Budget** | Your AI spend for the calendar month. Configurable, resets every month. | - -Trial and free accounts have a fixed AI budget, shared by AI chat and agents, that doesn't reset, plus a daily budget that resets at midnight UTC. Neither can be edited — upgrade to a paid plan to set your own budget. - -For the full list of limits and how soft limits work, see [Capping](/docs/user-guide/orioniq/agents-hub/#capping). +Find these limits before you roll AI features out to a team, not after. ## If AI is disabled diff --git a/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md b/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md index 77693949..a6aa69a0 100644 --- a/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md +++ b/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md @@ -160,6 +160,24 @@ If the rule includes any aggregation or group by field, the notification output ![Add email](https://dytvr9ot2sszz.cloudfront.net/logz-docs/siem-quick-start/siem-add-email-dec.gif) +### *(Optional)* Alert AI Analysis + +Security rules support the same AI-powered investigation as alerts. In the **Alert AI Analysis** step, turn the toggle on and Logz.io's AI Agent investigates the cause of the rule the moment it triggers, then delivers its findings to the recipients you choose. + +| Setting | Description | +|---|---| +| **Recipients** | By default the analysis goes to the same recipients as the rule. You can instead select recipients manually — useful when the write-up is for a different audience than the page. | +| **Runbook** | The procedure to follow for this rule. The analysis draws on it as context, and it guides whoever picks the rule up. | +| **Daily invocation cap** | The maximum analyses per day for this rule. Set 0 to block it completely, or leave it empty for unlimited. A **soft limit** sends a warning notification without blocking. | + +Give the rule a clear description — that description is the context the AI uses, so a vague one produces a vague analysis. + +Each analysis appears in the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/), where you can read it in full and rate it. Account-wide AI limits are set in [OrionIQ Settings → Capping](/docs/user-guide/orioniq/settings/#capping). + +:::note +Alert AI Analysis requires AI features to be enabled on your account. If the step is missing or the toggle is unavailable, contact [Logz.io support](https://logz.io/support-page/). +::: + ### Save your rule Click Save to save your rule. If the thresholds are passed and the rule is triggered, Logz.io will log the rule and send the configured notifications. diff --git a/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md b/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md index e077ca43..f7a707a0 100644 --- a/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md +++ b/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md @@ -164,7 +164,7 @@ The system combines the **Trigger if** time interval with the **Wait time** inte ### Activate AI Agent Analysis :::note -To use AI Agent Analysis, your alert must include a **Slack notification endpoint** and a **clear description**. +Give the alert a **clear description**. That description is the context the AI uses, so a vague one produces a vague analysis. ::: [AI Agent Analysis](/docs/user-guide/observability/ai-agent-analysis/) enables Logz.io’s AI Agent to automatically investigate the cause of an alert the moment it’s triggered—delivering fast, actionable insights to help you understand what happened and why. @@ -175,18 +175,29 @@ To enable it: ![AI Analysis](https://dytvr9ot2sszz.cloudfront.net/logz-docs/alerts/ai-agent-analysis-checked.png) -* Click **Configure endpoint** and select the Slack channel where the report should be delivered. +* Choose who receives the analysis — see [Recipients for the analysis](#recipients-for-the-analysis) below. ![notification endpoint](https://dytvr9ot2sszz.cloudfront.net/logz-docs/alerts/notification-endpoint.png) * Add a clear description to your alert—this gives the AI the context it needs to produce accurate and helpful results. -Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings will be sent to your selected **Slack channel** and stored in the **AI Agent chat history** for future reference. +Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings is sent to the recipients you chose and stored in the **AI Agent chat history** for future reference. Each run also appears in the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/), where you can read its full analysis and rate it. :::caution note AI Agent Analysis runs **once every hour**. ::: +#### Recipients for the analysis + +By default the analysis goes to the same recipients as the alert itself. You can instead select recipients manually, which is worth doing when the analysis is for a different audience than the page — for example the owning team gets the alert, while a shared channel gets the write-up. + +#### Runbook and instructions + +Alongside the analysis you can attach a **runbook** and **instructions**. Both are context the analysis draws on as well as guidance for whoever picks the alert up, so they do double duty: + +* **Instructions** — what the responder should do. Also see [Alert Instructions](/docs/open360/alerts/instructions/). +* **Runbook** — the procedure to follow, for alerts with an established response. + [Learn more about AI Agent Analysis](/docs/user-guide/observability/ai-agent-analysis/).

Select alert's output format & content

diff --git a/docs/user-guide/orioniq/agents-hub.md b/docs/user-guide/orioniq/agents-hub.md index 95ceff29..f588f536 100644 --- a/docs/user-guide/orioniq/agents-hub.md +++ b/docs/user-guide/orioniq/agents-hub.md @@ -29,9 +29,31 @@ The **Agents** tab displays a list of all agents in your account. Each agent row | **Activation** | Toggle to enable or disable the agent. | | **Invocation Cost** | The cost charged when this agent is triggered. | | **Daily Cap** | Per-agent daily invocation limit, configured in each agent's settings. | -| **Actions** | Additional actions available for the agent. | +| **Actions** | The agent's **Triggers** menu and its actions menu. | -To create a new agent directly from this page, click **+ Create New Agent** in the top right corner. +To create a new agent directly from this page, click **Build an Agent** in the top right corner. + +### Triggers + +Each row has a **Triggers** menu for running or wiring up the agent: + +| Action | Description | +|---|---| +| **Test Manually** | Run the agent now with a context you supply, without waiting for its trigger. Use it to check an agent's instructions before relying on them. | +| **Connect Alert** | Wire the agent to a Logz.io alert, so a triggered alert invokes it. | + +An action is unavailable when the agent's configuration doesn't allow it — for example, an agent that's disabled or capped. Hover the action to see why. + +### Row actions + +The actions menu (**⋯**) holds the rest: + +| Action | Description | +|---|---| +| **Edit Agent** / **View Agent** | Open the agent's configuration. Alert-managed and read-only agents open in view mode. | +| **See Invocations** | Jump to the Invocations tab, filtered to this agent. | +| **API References** | Show ready-to-copy requests for invoking this agent over the [OrionIQ API](/docs/user-guide/orioniq/api/). | +| **Delete Agent** | Remove the agent. | ### Filter the list @@ -50,21 +72,17 @@ The **Invocations** tab offers an **Output** filter instead of **Activation**, s ### Capping -Click the **Capping** button to manage AI spend and invocation limits across your agents. - -| Limit | Description | -|---|---| -| **Daily Invocation Limit** | System-enforced daily invocation limit across your account. Resets at midnight UTC. | -| **Account Daily Token Limit** | System-enforced daily token limit for AI chat across your account. Resets at midnight UTC. | -| **Monthly Budget** | Your configurable monthly budget. Resets every calendar month. | +Admins can click the **Capping** button to manage AI spend and invocation limits across the account. These are the same limits as **OrionIQ > Settings > Capping** — see [Capping](/docs/user-guide/orioniq/settings/#capping). -Trial and free accounts see a fixed **Budget**, shared by AI Chat and AI Agents, that doesn't reset, plus an additional **Daily Budget** that resets at midnight UTC. These limits can't be edited — upgrade to a paid plan to set your own budget. +### Permissions -Limits can also carry a **soft limit**: a warning threshold that sends a notification when usage crosses it, without stopping agents from running. +Users with the Read-only role have full read access to OrionIQ. They can: -### Permissions +* Browse agents, the Agents Hub, and invocation history. +* View the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/), connected [Integrations](/docs/user-guide/orioniq/integrations/), [Memory](/docs/user-guide/orioniq/memory/), and the [Marketplace](/docs/user-guide/orioniq/marketplace/) — including agent templates they may want to request. +* Use OrionIQ chat. -Users with the Read-only role can view agents, the Agents Hub, and run history, and can use OrionIQ chat, but can't create, edit, activate, or manually trigger agents. +They can't create, edit, activate, delete, or manually trigger agents, and they can't install a marketplace agent or connect an integration. ## Invocations tab @@ -102,7 +120,7 @@ Shows the final analysis report generated by the agent. This may include finding After reviewing an invocation's output, you can rate the accuracy and usefulness of the agent's results from the **Output** tab. Once you've rated a run, you can also add a free-text comment explaining the rating, and edit it later. -Feedback helps improve AI performance over time and gives you a way to track agent reliability. For eligible accounts, it also feeds the lessons an agent learns and applies to later runs — see [Enable or disable a lesson](/docs/user-guide/orioniq/api/#enable-or-disable-a-lesson). +Feedback helps improve AI performance over time and gives you a way to track agent reliability. You can monitor feedback scores and coverage across all your agents from the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/), and submit or read feedback programmatically with the [OrionIQ API](/docs/user-guide/orioniq/api/). diff --git a/docs/user-guide/orioniq/api.md b/docs/user-guide/orioniq/api.md index 97cac1e0..8d300ab4 100644 --- a/docs/user-guide/orioniq/api.md +++ b/docs/user-guide/orioniq/api.md @@ -1,14 +1,14 @@ --- -sidebar_position: 8 +sidebar_position: 9 title: OrionIQ API image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg -description: Trigger OrionIQ agents, poll for results, send follow-ups, submit feedback, and manage learned lessons using the OrionIQ API. -keywords: [OrionIQ, API, agents, trigger agent, agent run, feedback, lessons, api token, automation] +description: Trigger OrionIQ agents, poll for results, send follow-ups, and submit feedback using the OrionIQ API. +keywords: [OrionIQ, API, agents, trigger agent, agent run, feedback, api token, automation] --- Agents configured with the **API** trigger run on demand when you call the OrionIQ API. Use it to start a run from a CI pipeline, an incident workflow, or any external system, then poll for the result. -To find an agent's ID and a ready-to-copy request for each endpoint, open the agent in the [Agents Hub](/docs/user-guide/orioniq/agents-hub/) and go to the **API** section of its configuration. +To get an agent's ID and a ready-to-copy request for each endpoint, open the agent's actions menu in the [Agents Hub](/docs/user-guide/orioniq/agents-hub/) and select **API References**. ## Authentication @@ -146,7 +146,7 @@ A disabled agent does not start new runs, whatever its trigger configuration. POST /v2/ai-agent/<>/feedback ``` -Rates one or more runs. Feedback appears in the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/) and, for eligible accounts, feeds the lessons the agent learns. +Rates one or more runs. Feedback appears in the [Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/). ### Sample request @@ -199,53 +199,6 @@ GET /v2/ai-agent/<>/feedback/ Returns the feedback record for a run, in the same shape as a single entry in the Submit feedback response. Returns `404` when the run has no feedback. -## List learned lessons - -``` -GET /v2/ai-agent/<>/lessons -``` - -Returns the lessons the agent has learned from feedback. A lesson records a situation the agent met, the rule it derived, and why. - -### Response - -```json -{ - "lessons": [ - { - "lessonId": "", - "status": "active", - "situation": "", - "rule": "", - "whyNote": "", - "feedbackRef": "" - } - ] -} -``` - -Only `active` lessons are added to the agent's instructions on later runs. - -## Enable or disable a lesson - -``` -PUT /v2/ai-agent/<>/lessons//status -``` - -Turns a lesson on or off. Use this to retire a lesson the agent should stop applying. - -### Sample request - -```shell -curl -X PUT \ - https://<>/v2/ai-agent/<>/lessons//status \ - -H 'Content-Type: application/json' \ - -H 'X-API-TOKEN: <>' \ - -d '{"enabled": false}' -``` - -`enabled` is required and must be a boolean; anything else returns `400`. The response returns the updated lesson in the same shape as a List learned lessons entry, with `status` set to `active` or `disabled`. An unknown lesson returns `404`. - :::note -Agents don't have to be reachable over the API to be rated. Runs started by a Scheduled, Deployment, or Alert trigger can be rated from the Agents Hub, and the same feedback and lessons endpoints apply to them. +Agents don't have to be reachable over the API to be rated. Runs started by a Scheduled, Deployment, or Alert trigger can be rated from the Agents Hub, and the same feedback endpoints apply to them. ::: diff --git a/docs/user-guide/orioniq/create-agent.md b/docs/user-guide/orioniq/create-agent.md index 17f157d7..b41da8a9 100644 --- a/docs/user-guide/orioniq/create-agent.md +++ b/docs/user-guide/orioniq/create-agent.md @@ -34,15 +34,27 @@ Switch to the **Configure** tab to set the agent's properties and behavior. ![Configure tab with agent settings](https://dytvr9ot2sszz.cloudfront.net/logz-docs/orioniq/orioniq-configure-agent.png) -### General information +The configuration is a series of sections. Work through them in order. + +### General Information | Field | Description | |---|---| | **Agent Name** | A descriptive name for your agent. | | **Description** | A brief explanation of what the agent does. | -| **Payload (JSON)** | Optional JSON payload to pass additional parameters to the agent. Fields sent on an API invocation override the matching fields here. | +| **Active** | Enable or disable the agent. When disabled, it won't run regardless of its trigger. For an alert-linked agent this is managed from the alert definition. | + +### Agent Definition -### Trigger +The structured specification the agent runs from, generated for you on the **Create** tab. You can edit it directly here. Fields sent on an API invocation override the matching fields in the definition. + +### Configuration + +| Field | Description | +|---|---| +| **Type** | The agent type. Determines how the agent is priced and which data it can reach. | +| **Trigger** | How the agent runs — see below. | +| **Schedule** | For a Scheduled trigger, the interval the agent runs on. | Choose how the agent will run by selecting a trigger type: @@ -53,9 +65,21 @@ Choose how the agent will run by selecting a trigger type: | **Deployment** | The agent runs automatically when a deployment event is detected. | | **Alert** | The agent runs automatically when a Logz.io alert is triggered. | -### Daily invocation cap +### Daily Invocation Cap + +Each agent invocation incurs a cost. Set the maximum number of invocations per day to control your usage budget. Leave it empty for unlimited invocations, or set it to 0 to block the agent completely. -Each agent invocation incurs a cost. You can set a maximum number of invocations per day to control your usage budget. Leave this field empty for unlimited invocations, or set it to 0 to fully block the agent from running. +You can also set a **soft limit**: when daily invocations reach it, a warning notification is sent but invocations are not blocked. + +Account-wide limits are set separately — see [Settings → Capping](/docs/user-guide/orioniq/settings/#capping). + +### Data Sources + +Pick the observability platform and accounts this agent can query. Toggle the scope chips to choose Logs, Metrics, or both — each scope has its own accounts list. + +### Integrations + +Connect third-party tools — Slack, Jira, Confluence, and the rest — that this agent can use as context. Only integrations your account has already connected are available here; connect new ones from the [Integrations](/docs/user-guide/orioniq/integrations/) page. ### Notification recipients @@ -64,10 +88,6 @@ Configure where agent results are sent after each invocation. You can select fro - **Email addresses** of team members. - **Pre-configured notification endpoints** such as Slack channels, Microsoft Teams webhooks, or custom API endpoints. -### Activation - -Use the **Active** toggle to enable or disable the agent. When disabled, the agent will not run regardless of its trigger configuration. - ## Finalize and create Once you've reviewed the agent definition and configured the settings, click **Create Agent**. The agent becomes available in the [Agents Hub](/docs/user-guide/orioniq/agents-hub/) where you can monitor its invocations and manage its settings. diff --git a/docs/user-guide/orioniq/index.md b/docs/user-guide/orioniq/index.md index 9ce18f50..1b40842c 100644 --- a/docs/user-guide/orioniq/index.md +++ b/docs/user-guide/orioniq/index.md @@ -16,13 +16,15 @@ You can access OrionIQ from the left navigation menu. The OrionIQ section includ **[Marketplace](/docs/user-guide/orioniq/marketplace/)**: Browse and install pre-built agent templates for common use cases such as incident analysis, deployment validation, compliance scanning, and security monitoring. -**[Utilities](/docs/user-guide/orioniq/utilities/)**: Connect external systems to your agents. Utilities provide agents with context and interoperability by integrating with tools like ticketing systems, collaboration platforms, and cloud services. +**[Integrations](/docs/user-guide/orioniq/integrations/)**: Connect external systems to your agents. Integrations provide agents with context and interoperability by integrating with tools like ticketing systems, collaboration platforms, and cloud services. **[Usage & Performance Dashboard](/docs/user-guide/orioniq/usage-performance/)**: Monitor agent usage statistics, track invocation volume, review feedback trends, and evaluate overall agent performance. **[Memory](/docs/user-guide/orioniq/memory/)**: Give OrionIQ lasting context about your environment, your services, and how you work. -**[OrionIQ API](/docs/user-guide/orioniq/api/)**: Trigger agents from external systems, poll for results, submit feedback, and manage the lessons agents learn. +**[Settings](/docs/user-guide/orioniq/settings/)**: Set your theme, name the assistant, cap AI spend, and see where your data and LLM are hosted. + +**[OrionIQ API](/docs/user-guide/orioniq/api/)**: Trigger agents from external systems, poll for results, and submit feedback. :::note OrionIQ uses AI to analyze your data. Always review agent results and check for accuracy. diff --git a/docs/user-guide/orioniq/integrations.md b/docs/user-guide/orioniq/integrations.md new file mode 100644 index 00000000..37be993b --- /dev/null +++ b/docs/user-guide/orioniq/integrations.md @@ -0,0 +1,102 @@ +--- +sidebar_position: 5 +title: Integrations +image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg +description: Connect external systems to OrionIQ agents so they can use them as context and act on them. +keywords: [OrionIQ, integrations, connections, external systems, collaboration, ticketing, observability] +--- + +Integrations connect your OrionIQ agents to external systems, giving them access to additional context and enabling interoperability across your toolchain. For example, an agent can pull data from a ticketing system or push results to a collaboration platform. + +To access Integrations, navigate to **OrionIQ > Integrations** in the left navigation menu. + +![OrionIQ Integrations](https://dytvr9ot2sszz.cloudfront.net/logz-docs/orioniq/orioniq-utilities.png) + +The page has two tabs: + +* **Catalog** — every integration OrionIQ supports, and where you connect one. +* **Management** — the connections your account has already made, and their health. + +## Catalog + +Integrations are organized into the following categories: + +| Category | Examples | +|---|---| +| **Observability** | Logz.io, Datadog, Grafana, AWS CloudWatch, New Relic | +| **Incident Management** | PagerDuty, Opsgenie, FireHydrant, incident.io, Rootly | +| **Communication** | Slack, Microsoft Teams | +| **Service Management** | Jira Cloud, Jira Service Management, Intercom, Asana | +| **Knowledge & Content** | Confluence Cloud, Agility CMS | +| **Developer Tools** | GitHub, GitLab, Argo CD | +| **Cloud & Infrastructure** | AWS EC2, AWS ECS, AWS EKS, AWS Lambda | +| **Databases & Warehouses** | AWS DynamoDB, AWS RDS, Azure SQL Database, ClickHouse, Databricks | +| **Security & Identity** | 1Password, AbuseIPDB, Aikido Security | +| **Analytics & BI** | Amplitude, Databox, Fathom | +| **AI & Machine Learning** | Anthropic, AI21 Labs | +| **Files & Docs** | Airtable, Box, Canva | +| **Sales & CRM** | Salesforce, Gong, Apollo.io | +| **Marketing & Social** | ActiveCampaign, Ahrefs | +| **Finance & Payments** | AWS Cost Explorer, Azure Cost Management, Alpaca | +| **HR & People** | BambooHR, Ashby, Breezy HR | + +Use the search bar to find a specific integration, or click a category tab to filter the list. The catalog is ordered by popularity, so the integrations most accounts connect appear first. + +## Connect an integration + +Click **Connect** on an integration and provide its credentials. Which method an integration uses depends on the integration: + +| Method | Description | +|---|---| +| **API Key** | Connect using the provider's API token. This is what most integrations use. | +| **Basic Auth** | Connect with an email address and API token. | +| **None** | A few public data sources, such as MITRE ATT&CK and Hacker News, need no credentials at all. | + +## Management + +The **Management** tab lists your account's connections: + +| Column | Description | +|---|---| +| **Integration** | The connected integration. | +| **Space** | The space the connection belongs to. | +| **Status** | The connection's health — see below. | +| **Connected by** | The user who created the connection. | +| **Used by** | How many agents use the connection. | +| **Connection** | The connection's name, and the authentication method it uses. | +| **Updated by** | The user who last changed the connection. | +| **Updated at** | When the connection was last changed. | +| **Validated at** | When the connection's credentials were last verified. | + +A connection reports one of these statuses: + +| Status | Meaning | +|---|---| +| **Connected** | The credentials are valid and the integration is reachable. | +| **Needs reauth** | The credentials were rejected and must be re-entered. | +| **Expired** | The credentials are no longer valid. | +| **Unreachable** | The provider couldn't be reached. | +| **Needs credentials** | The connection has no usable credentials. | + +Open a connection's actions menu to **Configure** its credentials, **Revalidate** it against the provider, or **Disconnect** it. + +## Logz.io API access + +The Logz.io integration is connected by default and gives agents access to your observability data. You can also grant agents scoped access to the Logz.io public API, per account: + +| Scope | Grants | +|---|---| +| **Telemetry** | Logs and metrics access for the agent. Always on for every accessible account and not configurable. | +| **Read** | The agent can call the Logz.io public API but can't change anything. | +| **Write** | The agent can create and update Logz.io objects. Implies Read. | +| **Admin** | The agent has the same role as Manage API Tokens. Implies Read and Write. | + +Enabling API access creates one system-generated API token per selected account, at the highest scope you chose. Changing or turning off API access deletes that token; agents keep their telemetry access, and a lower scope gets a new token at that scope. + +Owner, sub-accounts, and Security accounts have a public API. Metrics, Timeless, and Restored accounts do not, so API scopes aren't available for them. + +To request an integration that isn't yet available, click **Add to Wish List** on the integration you're interested in. This helps Logz.io prioritize which integrations to support next. + +:::note +Integrations is an evolving capability. New integrations are added regularly based on user demand. +::: diff --git a/docs/user-guide/orioniq/settings.md b/docs/user-guide/orioniq/settings.md new file mode 100644 index 00000000..42548724 --- /dev/null +++ b/docs/user-guide/orioniq/settings.md @@ -0,0 +1,53 @@ +--- +sidebar_position: 8 +title: Settings +image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg +description: Configure your OrionIQ theme, the assistant's name, AI spend limits, and where your account data and LLM are hosted. +keywords: [OrionIQ, settings, capping, budget, limits, theme, regions, assistant name] +--- + +OrionIQ settings are grouped into four sections, reachable from **Settings** in OrionIQ. + +## User + +Settings that apply to you alone. + +| Setting | Description | +|---|---| +| **Theme** | Choose how OrionIQ looks for you — Light or Dark. | +| **Email** | The email of the logged-in user. Read-only. | + +## Account + +Settings that apply to everyone on the account. + +| Setting | Description | +|---|---| +| **OrionIQ name** | The name everyone on the account uses to address the assistant. It appears in the sidebar. | +| **OrionIQ Regions** | Where your account data is stored (**Data hosting**) and where the LLM serving OrionIQ runs (**LLM model hosting**). Both are set during account provisioning and can't be edited. | + +## Capping + +Controls what OrionIQ is allowed to spend. Admins can also reach this from the **Capping** button on the [Agents Hub](/docs/user-guide/orioniq/agents-hub/). + +| Limit | Description | +|---|---| +| **Monthly Budget** | Your configurable AI budget for the calendar month. Resets every month. | +| **Daily Invocation Limit** | System-enforced daily invocation limit across your account. Resets at midnight UTC. | +| **Account Daily Token Limit** | System-enforced daily token limit for AI chat across your account. Resets at midnight UTC. | + +A limit can carry a **soft limit** — a warning threshold that sends a notification when usage crosses it, without blocking invocations. + +### Trial and free accounts + +Trial and free accounts get a fixed **Budget**, shared by AI Chat and AI Agents, that **does not reset**, plus an additional **Daily Budget** that resets at midnight UTC. AI pauses for the rest of the day when the daily budget is reached. + +Neither limit can be edited. Upgrade to a paid plan to set your own budget. + +## Logz.io + +Account-level settings beyond OrionIQ — billing, users, regions, and platform configuration — live in the Logz.io console. Click **Open Logz.io settings** to go there. + +:::note +Per-agent daily caps are set on the agent itself, not here. See [Create an Agent](/docs/user-guide/orioniq/create-agent/). +::: diff --git a/docs/user-guide/orioniq/utilities.md b/docs/user-guide/orioniq/utilities.md deleted file mode 100644 index 11f53ac6..00000000 --- a/docs/user-guide/orioniq/utilities.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -sidebar_position: 5 -title: Utilities -image: https://dytvr9ot2sszz.cloudfront.net/logz-docs/social-assets/docs-social.jpg -description: Connect external systems to OrionIQ agents using Utilities for context and interoperability. -keywords: [OrionIQ, utilities, integrations, external systems, collaboration, ticketing, CI/CD] ---- - -Utilities connect your OrionIQ agents to external systems, giving them access to additional context and enabling interoperability across your toolchain. For example, an agent can pull data from a ticketing system or push results to a collaboration platform. - -To access Utilities, navigate to **OrionIQ > Utilities** in the left navigation menu. - -![OrionIQ Utilities](https://dytvr9ot2sszz.cloudfront.net/logz-docs/orioniq/orioniq-utilities.png) - -## Browse available utilities - -Utilities are organized into the following categories: - -| Category | Examples | -|---|---| -| **Monitoring & Observability** | Logz.io (connected by default), and other monitoring platforms. | -| **Incident Management** | PagerDuty, Opsgenie, and similar incident response tools. | -| **Collaboration** | Slack, Microsoft Teams, and other messaging platforms. | -| **Knowledge Management** | Confluence, Notion, and documentation platforms. | -| **Ticketing** | Jira, ServiceNow, and other issue tracking systems. | -| **Cloud Platform** | AWS, Azure, GCP, and other cloud providers. | -| **Container & Orchestration** | Kubernetes and container management tools. | -| **CI/CD** | Jenkins, GitHub Actions, and other deployment pipelines. | -| **Version Control** | GitHub, GitLab, and other source control platforms. | -| **Auth & IAM** | Identity and access management systems. | -| **Secrets** | Secret management tools such as HashiCorp Vault. | -| **Database** | Database management and querying tools. | - -Use the search bar to find a specific utility, or click a category tab to filter the list. - -## Connect a utility - -Click **Connect** on a utility and choose an authentication method. Which methods a utility offers depends on the utility: - -| Method | Description | -|---|---| -| **OAuth 2.0** | Authorize Logz.io through the provider's own consent flow. | -| **API Key** | Connect using the provider's API token. | -| **Basic Auth** | Connect with an email address and API token. | - -## Logz.io API access - -The Logz.io utility is connected by default and gives agents access to your observability data. You can also grant agents scoped access to the Logz.io public API, per account: - -| Scope | Grants | -|---|---| -| **Telemetry** | Logs and metrics access for the agent. Always on for every accessible account and not configurable. | -| **Read** | The agent can call the Logz.io public API but can't change anything. | -| **Write** | The agent can create and update Logz.io objects. Implies Read. | -| **Admin** | The agent has the same role as Manage API Tokens. Implies Read and Write. | - -Enabling API access creates one system-generated API token per selected account, at the highest scope you chose. Changing or turning off API access deletes that token; agents keep their telemetry access, and a lower scope gets a new token at that scope. - -Owner, sub-accounts, and Security accounts have a public API. Metrics, Timeless, and Restored accounts do not, so API scopes aren't available for them. - -To request access to a utility that isn't yet available, click **Add to Wish List** on the utility you're interested in. This helps Logz.io prioritize which integrations to support next. - -:::note -Utilities is an evolving capability. New integrations are added regularly based on user demand. -::: diff --git a/static/_redirects b/static/_redirects index 62e06c4f..baf5be3f 100644 --- a/static/_redirects +++ b/static/_redirects @@ -1200,4 +1200,8 @@ /docs/logz/get-cloud-trail https://api-docs.logz.io/docs/logz/get-cloud-trail/ /docs/logz/put-alert-rules-by-uid https://api-docs.logz.io/docs/logz/put-alert-rules-by-uid/ /docs/logz/put-alert-rules-by-uid/ https://api-docs.logz.io/docs/logz/put-alert-rules-by-uid/ +# OrionIQ: Utilities renamed to Integrations +/docs/user-guide/orioniq/utilities/ /docs/user-guide/orioniq/integrations/ +/docs/user-guide/orioniq/utilities /docs/user-guide/orioniq/integrations/ + /:splat / From 3d55bcdf268ea777a28cc7c3b2f5a0e3e3eb805a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 27 Aug 2026 17:48:42 +0000 Subject: [PATCH 3/3] Second review round: agent definition fields, AI Analysis agent, invocation history Document the Agent Definition fields including Agent tools, correct the "AI Agent chat history" claim to the agent's invocation history, and add the configurable AI Analysis agent (integrations, tools, daily cap) to the alert and security rule pages. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016YV5STTjgrMt8UX44CVHjr --- agents.md | 17 +++++++++++++++-- .../open360/alerts/configure-alerts-explore.md | 14 +++++++++++++- .../security-rules/manage-security-rules.md | 14 +++++++++++++- .../configure-alerts-explore.md | 14 +++++++++++++- docs/user-guide/orioniq/create-agent.md | 18 +++++++++++++++++- 5 files changed, 71 insertions(+), 6 deletions(-) diff --git a/agents.md b/agents.md index 53ddf721..bfe6a66c 100644 --- a/agents.md +++ b/agents.md @@ -46,11 +46,17 @@ Match the product's own words, not an older doc's: | Agents / Invocations (the Agents Hub tabs) | — | | Alert AI Analysis (the alert and rule step) | — | -## Open question for the docs team +## Agreed follow-up: the AI docs refactor `docs/open360/observability/` and `docs/user-guide/observability/` are the SAME three pages twice — the "Observability IQ" category at both `/docs/category/observability-iq/` and `/docs/category/observability-iq-1/`, holding `assistantiq.md` (AI Agent), `ai-agent-analysis.md`, and `faq.md`. Their content also overlaps the OrionIQ pages. -Consolidating or deleting them is a **migration, not a cleanup**: 20 inbound links across 14+ pages point at them, and `onBrokenLinks: 'throw'` means every one has to be repointed, with `static/_redirects` entries for the public URLs. Don't do it as a side effect of a sync run — it needs a decision on which tree survives. +**The direction is decided** (ralongit, PR #960): AI documentation should sit where it sits in the product. + +* Open 360 and Cloud SIEM inner pages keep only what belongs to them: a reference to the **OrionIQ chat drawer** from the relevant nested doc (Explore, Dashboards, App 360, K8s 360, …), and the **Alert AI Analysis** agents. +* Everything else AI-related lives in the **OrionIQ** section only. +* The **FAQ** gets split per platform — one for Open 360, one for OrionIQ — rather than one page covering both. + +This is a **migration, not a cleanup**, and it's a separate PR: 20 inbound links across 14+ pages point into those pages, `onBrokenLinks: 'throw'` means every one has to be repointed, and each removed public URL needs a `static/_redirects` entry. Don't attempt it as a side effect of a sync run. ## Recurring documentation patterns @@ -112,3 +118,10 @@ Notes for next time: * **Documenting the unreleased.** See the lessons section above. * **Missing surfaces.** The Triggers menu, the Management tab, the Settings page, and most of the agent editor were all shipped and undocumented. A commit-history scan will not find these — they predate the window. Walk the product's nav and tabs against the doc tree once per run, not just the diff. * **Two pages the scan missed entirely** because they live outside `docs/user-guide/orioniq/`: the alert AI Analysis section (whose Slack-endpoint requirement ORIONIQ-1298 had made obsolete) and the SIEM security rules page, which never documented Alert AI Analysis at all. Grep the whole `docs/` tree for AI surfaces, not just the OrionIQ directory. + +Second round, same PR: + +* **Deleting a stale field is not the same as documenting what replaced it.** The agent editor's "Payload (JSON)" is now the **Agent Definition** section — five friendly fields (Runbook, Guidelines, **Agent tools**, Output detail, Structured output, from `AgentEdit/agent-definition-fields.constants.ts`) with the raw JSON behind an **Advanced · Agent Definition** accordion. Dropping the old row without naming those read as a deletion. `SPEC_FRIENDLY_FIELDS` and `AGENT_KIND_OPTIONS` carry the labels and help text verbatim. +* **`spec.agents` (Agent tools) drives the Data Sources picker**, and the form refuses to save until every declared lane has a source. Two sections that look independent in the doc are coupled in the product. +* **Alert / rule AI Analysis creates a real agent**, editable in the Agents Hub like any other — so Integrations, Agent tools and its own daily cap are all configurable, none of which the alert form itself shows. The copy is in `AIAgentRCA/RcaNotes.tsx` ("Configure agent after saving", "Agent configuration is managed in the Agent Hub"). +* **AI Agent Analysis output is stored in the agent's invocation history, NOT in "AI Agent chat history."** That phrasing was inherited from the existing page and is wrong; the analysis never lands in a chat. diff --git a/docs/open360/alerts/configure-alerts-explore.md b/docs/open360/alerts/configure-alerts-explore.md index 95d72fe6..638ed180 100644 --- a/docs/open360/alerts/configure-alerts-explore.md +++ b/docs/open360/alerts/configure-alerts-explore.md @@ -212,12 +212,24 @@ To enable it: * Add a clear description to your alert—this gives the AI the context it needs to produce accurate and helpful results. -Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings is sent to the recipients you chose and stored in the **AI Agent chat history** for future reference. Each run also appears in the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/), where you can read its full analysis and rate it. +Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings is sent to the recipients you chose, and every run is stored in the agent's **invocation history**, where you can read the full analysis and rate it — see the Invocations tab of the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/). :::caution note AI Agent Analysis runs **once every hour**. ::: +#### Configure the agent + +Enabling AI Agent Analysis creates an OrionIQ agent for the alert. Select **Configure agent after saving** to open it right after you save, or manage it later from the Agents Hub — the alert form links to it with **Manage in Agent Hub**. + +The agent is editable like any other, so beyond the settings on this page you can: + +* Set its instructions, guidelines, and **Agent tools**. +* Give it **Integrations** — Slack, Jira, Confluence, and the rest — so the analysis can draw on them. +* Adjust its own **daily invocation cap** and soft limit, independently of your account-wide caps. + +See [Create an Agent](/docs/user-guide/orioniq/create-agent/) for what each section does. + #### Recipients for the analysis By default the analysis goes to the same recipients as the alert itself. You can instead select recipients manually, which is worth doing when the analysis is for a different audience than the page — for example the owning team gets the alert, while a shared channel gets the write-up. diff --git a/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md b/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md index a6aa69a0..0b164538 100644 --- a/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md +++ b/docs/user-guide/cloud-siem/security-rules/manage-security-rules.md @@ -172,7 +172,19 @@ Security rules support the same AI-powered investigation as alerts. In the **Ale Give the rule a clear description — that description is the context the AI uses, so a vague one produces a vague analysis. -Each analysis appears in the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/), where you can read it in full and rate it. Account-wide AI limits are set in [OrionIQ Settings → Capping](/docs/user-guide/orioniq/settings/#capping). +Every run is stored in the agent's invocation history, where you can read the full analysis and rate it — see the Invocations tab of the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/). Account-wide AI limits are set in [OrionIQ Settings → Capping](/docs/user-guide/orioniq/settings/#capping). + +#### Configure the agent + +Turning the toggle on creates an OrionIQ agent for the rule, and you can update it at any time. Select **Configure agent after saving** to open it right after you save, or manage it later from the Agents Hub — the rule form links to it with **Manage in Agent Hub**. + +The agent is editable like any other, so beyond the settings above you can: + +* Set its instructions, guidelines, and **Agent tools**. +* Give it **Integrations** — Slack, Jira, Confluence, and the rest — so the analysis can draw on them. +* Adjust its own daily cap and soft limit, independently of your account-wide caps. + +See [Create an Agent](/docs/user-guide/orioniq/create-agent/) for what each section does. :::note Alert AI Analysis requires AI features to be enabled on your account. If the step is missing or the toggle is unavailable, contact [Logz.io support](https://logz.io/support-page/). diff --git a/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md b/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md index f7a707a0..03e95e69 100644 --- a/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md +++ b/docs/user-guide/explore/explore-log-alerts/configure-alerts-explore.md @@ -181,12 +181,24 @@ To enable it: * Add a clear description to your alert—this gives the AI the context it needs to produce accurate and helpful results. -Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings is sent to the recipients you chose and stored in the **AI Agent chat history** for future reference. Each run also appears in the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/), where you can read its full analysis and rate it. +Once triggered, the AI Agent will analyze related logs, metrics, and patterns. A summary of its findings is sent to the recipients you chose, and every run is stored in the agent's **invocation history**, where you can read the full analysis and rate it — see the Invocations tab of the OrionIQ [Agents Hub](/docs/user-guide/orioniq/agents-hub/). :::caution note AI Agent Analysis runs **once every hour**. ::: +#### Configure the agent + +Enabling AI Agent Analysis creates an OrionIQ agent for the alert. Select **Configure agent after saving** to open it right after you save, or manage it later from the Agents Hub — the alert form links to it with **Manage in Agent Hub**. + +The agent is editable like any other, so beyond the settings on this page you can: + +* Set its instructions, guidelines, and **Agent tools**. +* Give it **Integrations** — Slack, Jira, Confluence, and the rest — so the analysis can draw on them. +* Adjust its own **daily invocation cap** and soft limit, independently of your account-wide caps. + +See [Create an Agent](/docs/user-guide/orioniq/create-agent/) for what each section does. + #### Recipients for the analysis By default the analysis goes to the same recipients as the alert itself. You can instead select recipients manually, which is worth doing when the analysis is for a different audience than the page — for example the owning team gets the alert, while a shared channel gets the write-up. diff --git a/docs/user-guide/orioniq/create-agent.md b/docs/user-guide/orioniq/create-agent.md index b41da8a9..2280e100 100644 --- a/docs/user-guide/orioniq/create-agent.md +++ b/docs/user-guide/orioniq/create-agent.md @@ -46,7 +46,21 @@ The configuration is a series of sections. Work through them in order. ### Agent Definition -The structured specification the agent runs from, generated for you on the **Create** tab. You can edit it directly here. Fields sent on an API invocation override the matching fields in the definition. +The specification the agent runs from, generated for you on the **Create** tab. You can refine it field by field here: + +| Field | Description | +|---|---| +| **Runbook** | Mandatory step-by-step procedure the agent follows, in order. | +| **Guidelines** | Custom instructions for the agent. | +| **Agent tools** | Which tool set the agent uses: **Log agent**, **Metric agent**, **Logs + Metrics (deep)**, or **Integration agent**. This decides what the agent can query, so it has to match the data sources you pick below. | +| **Output detail** | Response verbosity — **Summary** or **Detailed**. Ignored when a structured output schema is set. | +| **Structured output** | A JSON Schema for the agent's response, enforced at inference. Use it when a downstream system consumes the output. | + +The raw JSON behind these fields is under **Advanced · Agent Definition**, which is where the agent's payload lives. Fields sent on an API invocation override the matching fields in it — see the [OrionIQ API](/docs/user-guide/orioniq/api/). + +:::note +Structured output schemas must be flat: properties can be primitives or arrays of primitives, with no nested objects. +::: ### Configuration @@ -77,6 +91,8 @@ Account-wide limits are set separately — see [Settings → Capping](/docs/user Pick the observability platform and accounts this agent can query. Toggle the scope chips to choose Logs, Metrics, or both — each scope has its own accounts list. +Which scopes you have to fill in follows the **Agent tools** you chose above: an agent declaring a logs tool set needs a logs data source, and the agent won't save until every declared scope has one. + ### Integrations Connect third-party tools — Slack, Jira, Confluence, and the rest — that this agent can use as context. Only integrations your account has already connected are available here; connect new ones from the [Integrations](/docs/user-guide/orioniq/integrations/) page.