@inferagraph/log-analytics

@inferagraph/log-analytics

Azure Log Analytics datasource plugin for @inferagraph/core. Reads graph nodes, edges, and content from a Log Analytics workspace via KQL.

Migrating from @inferagraph/log-analytics-datasource?

pnpm remove @inferagraph/log-analytics-datasource
pnpm add @inferagraph/log-analytics

The class was renamed LogAnalyticsDatasource → LogAnalyticsDataSource (capital S). A new logAnalyticsDataSource(config) factory is the recommended on-ramp; direct new LogAnalyticsDataSource(config) remains as an escape hatch.

Three auth modes are supported:

• app-registration — server-side app registration with client secret
• managed-identity — Azure-hosted managed identity
• apim — route through an Azure API Management endpoint (no Azure SDK)

The first two use @azure/monitor-query and @azure/identity. The third uses globalThis.fetch (Node 20+).

SSR caveat: app-registration and managed-identity are server-side only. The client secret / managed identity must NEVER reach the browser. Use Next.js Server Components, Route Handlers, or other server-side code paths. For browser-callable scenarios, use the apim mode and put your APIM in front of the workspace.

Installation

pnpm add @inferagraph/log-analytics @inferagraph/core

@azure/monitor-query and @azure/identity are bundled as direct dependencies.

Usage

The datasource is configured with three things:

• auth — how to talk to Log Analytics
• queries — KQL strings (or builder functions) per operation
• mapping — which result columns become id, sourceId, targetId, type, etc.

The recommended on-ramp is the logAnalyticsDataSource(config) factory; direct new LogAnalyticsDataSource(config) is an escape hatch for subclassing or other advanced cases.

App registration (server-side)

import { logAnalyticsDataSource } from '@inferagraph/log-analytics';

const datasource = logAnalyticsDataSource({
  workspaceId: '00000000-0000-0000-0000-000000000000',
  workspaceName: 'graph-prod',
  auth: {
    kind: 'app-registration',
    tenantId: process.env.AZURE_TENANT_ID!,
    clientId: process.env.AZURE_CLIENT_ID!,
    clientSecret: process.env.AZURE_CLIENT_SECRET!,
  },
  queries: {
    nodes: 'GraphNodes_CL | project id=node_id, type=node_type, name',
    edges:
      'GraphEdges_CL | project edge_id, source=source_id, target=target_id, rel=rel_type',
    search: (ctx) =>
      `GraphNodes_CL | where name contains '${ctx.params.query}' | project id=node_id, type=node_type, name`,
  },
  mapping: {
    nodes: { idColumn: 'id', typeColumn: 'type' },
    edges: {
      idColumn: 'edge_id',
      sourceColumn: 'source',
      targetColumn: 'target',
      typeColumn: 'rel',
    },
  },
  timespan: { duration: 'P30D' },
});

await datasource.connect();
const view = await datasource.getInitialView();
await datasource.disconnect();

Server-side only. Do not import this from a 'use client' component — secrets must not ship to the browser.

Managed identity (Azure-hosted)

const datasource = logAnalyticsDataSource({
  workspaceId: process.env.AZURE_LA_WORKSPACE_ID!,
  workspaceName: 'graph-prod',
  auth: { kind: 'managed-identity' },
  queries: { /* …same as above… */ },
  mapping: { /* …same as above… */ },
});

Server-side only. The managed identity is bound to the Azure host and cannot be used from a browser.

APIM (HTTP via fetch)

const datasource = logAnalyticsDataSource({
  workspaceId: process.env.AZURE_LA_WORKSPACE_ID!,
  workspaceName: 'graph-prod',
  auth: {
    kind: 'apim',
    endpoint: 'https://api.example.com/log-analytics',
    headers: { 'Ocp-Apim-Subscription-Key': process.env.APIM_KEY! },
    // Optional: customize per-op routing or body shape
    buildRequest: (op, kql, ctx) => ({
      url: `https://api.example.com/log-analytics/${op}`,
      body: { workspaceId: ctx.workspaceId, query: kql },
    }),
  },
  queries: { /* …same as above… */ },
  mapping: { /* …same as above… */ },
});

The default APIM request is POST {endpoint} with body { workspaceId, query, op }. Override body and/or url via buildRequest. The executor accepts both response shapes:

• { rows: [{ ... }] } (already row-objects)
• { tables: [{ columns: [{name, ...}], rows: [[...], ...] }] } (Log Analytics REST shape)

Configuration reference

LogAnalyticsDataSourceConfig

Field	Type	Description
workspaceId	string	Log Analytics workspace GUID
workspaceName	string	Human label (used in error messages)
auth	LogAnalyticsAuth	Discriminated union — see auth modes above
queries	LogAnalyticsQueryConfig	Per-op KQL or (ctx) => kql
mapping	LogAnalyticsMapping	Column-name → id/source/target/type mapping
timespan	{ duration: string }	ISO 8601 duration. Default 'P1D'.

LogAnalyticsQueryConfig

Field	Required	Fallback if omitted
nodes	yes	—
edges	yes	—
node	no	filter nodes results in memory by id
neighbors	no	run nodes + edges, BFS in memory
search	no	search() throws
filter	no	filter() throws
content	no	getContent() returns undefined

LogAnalyticsMapping

Section	Required	Notes
nodes.idColumn	yes	Column whose value becomes NodeData.id
nodes.typeColumn	no	If set, value is exposed as attributes.type
edges.{idColumn, sourceColumn, targetColumn, typeColumn}	yes	All four required
content.{idColumn, bodyColumn}	yes (when queries.content set)	—
content.contentTypeColumn	no	Default content type is 'text'

Behavior notes

• getInitialView runs the nodes and edges queries, slices nodes to limit, then keeps only edges whose source AND target are in the returned node set.
• getNeighbors uses queries.neighbors if configured; otherwise falls back to in-memory BFS over queries.nodes + queries.edges. The depth parameter limits traversal.
• findPath is always an in-memory BFS over queries.nodes + queries.edges (KQL has no practical native path-finding for arbitrary graphs).
• All row attributes are preserved on NodeData.attributes / EdgeData.attributes (mirrors the CosmosDB datasource — the host application decides what's relevant).
• Pagination is applied in memory after row mapping.

License

MIT