# Log Analytics workspace (KQL) — optional

> Log Analytics workspace (KQL) — optional: fields, the check Connect and verify runs, the tools the agent gets and the read gate, from the connector catalog.

_How-to · Updated 2026-10-23 · Describes release 0.1.164_

> Generated from the connector catalog (`scripts/docs_integration_stubs.py`); the long form of every step is [Connect a datasource](/help/manage-connections.md#connect-a-datasource).

## Overview {#overview}

Optional. The Azure connection already covers ARM, Azure Monitor, the Activity Log and Resource Graph reads; add this only when you want KQL over a Log Analytics workspace (Sentinel / SIEM tables: SecurityAlert, SecurityIncident, SigninLogs, Syslog…) via the native sentinel_query tool. Read-only. Uses the same service principal as the Azure connection and needs the Log Analytics Reader role on the workspace.

Connector type key `sentinel`, kind `api`, listed under Logs, Security findings in the catalog.

## Setup {#setup}

### Before you start {#before-you-start}

- The `datasources.manage` permission; the built-in owner and operator roles carry it.
- The credential the form stores write-only (*Client secret*), created on the vendor side as described under [Installation](#installation) and scoped to reads.

### Installation {#installation}

Prepare the credential on the vendor side first, scoped to reads: the platform's read gate is a floor, not a substitute for a read-only identity. The connect dialog's **Connection guidance** column names the vendor-side steps and the exact read permissions for this type.

### Configuration {#configuration}

1. Open **Settings · Data in → Data sources** and select **Connect datasource**.
2. Under **Type**, choose **Log Analytics workspace (KQL) — optional**; the list groups the types by category.
3. Enter a **Connection name**; the connected list shows it, and per-connection agent tools are named after it.
4. Fill the fields in the table below.
5. Optionally, open **Optional · describe this environment** and say in **What should AIOps know about it?** what this system is and what matters; the agent reads it as the connection's description.
6. Under **Use this connection for**, choose **Investigate only** and select **Connect and verify**.

The form shows these fields, in this order; the **API key** column is the key to send through the REST API.

| Field (portal label) | API key | Stored as |
|---|---|---|
| Log Analytics workspace ID | `workspace_id` | plain |
| Directory (tenant) ID | `tenant_id` | plain |
| App (client) ID | `client_id` | plain |
| Client secret | `client_secret` | secret, write-only |

The same connection through the API (`POST /api/aiops/{tenant_id}/datasources`, `datasources.manage`; secret fields go in `secret_values`, which are stored write-only and never echoed):

```json
{
  "type_key": "sentinel",
  "name": "<name>",
  "description": "<what this is and what matters, for the agent>",
  "config": {
    "workspace_id": "<workspace id>",
    "tenant_id": "<tenant id>",
    "client_id": "<client id>"
  },
  "secret_values": {
    "client_secret": "<client secret>"
  },
  "role": "read",
  "enabled": true
}
```

### Validation {#validation}

**Connect and verify** (and **Test** on the row) runs an Entra client-credentials token for the Log Analytics audience (`https://api.loganalytics.io/.default`).

**You should see** a dialog titled `<connection name> is connected` with **Connected — verified from the control plane** (**Connected — verified by your private-network agent** when your agent ran the check). **Test** on the row later writes `ok · AAD client-credentials grant ok (Log Analytics scope)` into **Last test**. A green result proves the operation named in its detail and nothing more; **Audit perms** on the row reads what the credential can actually do where the vendor exposes that.

### If something fails {#if-something-fails}

The dialog shows **Needs a fix**, what to fix and the check's own detail; the row is saved either way. Select **Edit**, correct the field the detail names and save again, or select **Retry** once a cause outside the form (network, vendor-side permission) is fixed. The verdict strings **Test** can show (`failed · SSRF guard: '<host>' resolves to non-public address …`, `failed · reachable but auth rejected (HTTP 401/403)`, `failed · HTTP <code> <path>`, `failed · <field> not configured`, `failed · <ExceptionName>: …`) and what to do about each are in [Test a connection and read the failure](/help/manage-connections.md#troubleshooting), and every connection status word is in the [status and error reference](/help/status-and-error-reference.md#connection-statuses). A connected datasource the agent never uses is disabled, write-role, allow-listed to other pillars, or of a type platform staff disabled.

## Data collected {#data-collected}

What the agent gets from a `read` connection of this type:

- `sentinel_query` — the native tool bound to the first Log Analytics workspace (KQL) — optional connection (a second one gets `<name>_sentinel_query`). the Log Analytics query API is read-only by construction, so the tool is ungated

An investigation refuses a write through any connection tool, whatever the credential allows (`Investigation connections are read-only. This operation was not executed; prepare an incident change using a write connection and obtain approval.`); a fix runs through a write-role connection after approval. The exact rule table is under **The read/write gate in detail** in [Connections and remediation access](/help/read-and-write-roles.md#read-role-vs-write-role).

## Next steps {#next-steps}

- Select **Discover this connection** in the success dialog to find the services and dependencies behind it: [Launch a scan](/help/estate-harvest-and-xray.md#launch-a-scan).
- See what else each agent needs in [Choose your connection](/help/choose-your-connection.md#agent-needs).
- A fix never runs through this read connection; give approved fixes their own credential with [Write connections and approved fixes](/help/setup-write-connections.md).