Observability
Send a deployed Fabric app's browser telemetry to its own Application Insights resource and query it with rayfin telemetry — enable, deploy, instrument, verify, investigate, and disable.
Use Observability to see what a deployed Fabric app does in users' browsers — the pages they view and the events your code emits — and to query that telemetry from the CLI while you investigate a problem. Rayfin allocates one Application Insights resource per deployed app, gives the app its connection string at runtime, and runs your KQL queries against that resource.
Warning
Observability is experimental. The rayfin telemetry commands need no feature flag, but allocating the Application Insights resource and querying it both require Fabric service-side telemetry enablement for the target workspace; no local setting turns it on. Querying also needs Write permission on the app item. The browser distribution it builds on, @microsoft/opentelemetry-browser, is a beta release.
Disabling telemetry and then running rayfin up deletes the app's Application Insights resource and all telemetry collected in it. Re-enabling creates a new, empty resource.
How it works
| Source | What reaches the app's Application Insights resource | What you set up |
|---|---|---|
| Browser frontend | Page views, plus the custom events you emit as named OpenTelemetry log records. No automatic Fetch/XHR, console, or error collection. | Install and initialize @microsoft/rayfin-telemetry/browser, then emit events. |
| Deployed Functions | rayfin up points the functions' telemetry destination at the app's resource when Functions and telemetry are both enabled. | Enable both services and deploy. |
| Fabric platform | Nothing. Fabric's internal monitoring stays separate. | — |
| Rayfin CLI usage | Nothing. CLI usage telemetry is a separate product channel. | RAYFIN_TELEMETRY_OPTOUT=1 opts out of CLI usage telemetry only. |
Prerequisites
- A Rayfin 2.0 project you deploy with
rayfin upto an approved Fabric workspace. - Fabric service-side telemetry enablement for that workspace. Ask your Fabric environment operator; it cannot be enabled from the project.
- Server-written runtime configuration for static deployments, a separate service-side setting, so the served
rayfin.config.jsoncarries the connection string. - Write permission on the app item, to run queries.
- A frontend built with a bundler, such as the Vite setup in the Rayfin templates, running in a current version of Chrome, Edge, Firefox, Opera, or Safari.
Enable telemetry
From inside the project:
npx rayfin telemetry enableThe command sets one key in rayfin.yml and prints ✅ Telemetry enabled.:
services:
telemetry:
enabled: trueIt changes local configuration only; nothing is allocated until you deploy. If telemetry is already enabled, it prints Telemetry is already enabled. No change was made. Do not put a connection string, resource ID, or credential in this block — Rayfin allocates and stores them for you.
Deploy
Preview the target, then deploy:
npx rayfin login
npx rayfin up --dry-run
npx rayfin upWith telemetry enabled, deployment:
- Sends the setting to the Fabric backend, which checks the service-side enablement and allocates an Application Insights resource for the app, or reuses the one it already allocated.
- Stores the resource and its connection string with the app.
- Installs the query adapter that
rayfin telemetry queryuses. A query never installs a missing adapter. - Points the app's deployed Functions at the same resource, when Functions are enabled.
- Writes the connection string into the hosted
rayfin.config.jsonasapplicationInsightsConnectionString.
A successful deployment does not prove the browser received the connection string: the rayfin.config.json the CLI builds locally does not contain it. Check the served file.
Check the connection string
Sign in to the deployed app, open the browser developer console on the app's own document — not the outer Fabric portal frame — and run:
const response = await fetch('/rayfin.config.json', { cache: 'no-store' });
if (!response.ok) throw new Error(`Runtime configuration request failed: HTTP ${response.status}`);
const config = await response.json();
console.log({
hasConnectionString: Boolean(config.applicationInsightsConnectionString),
workspaceId: config.workspaceId,
itemId: config.itemId,
});applicationInsightsConnectionString is present only when telemetry is enabled and a resource has been allocated. Confirm that workspaceId and itemId identify the app you deployed. If your app serves its runtime configuration from a custom base path, fetch the URL its client uses.
In app code, read the same value from the client:
const connectionString = rayfinClient.runtimeConfig?.applicationInsightsConnectionString;The client has it only when you create it with the runtimeConfig returned by resolveRayfinConfig(). Under npm run dev there is no served rayfin.config.json, so the value is absent and browser telemetry stays off. Test telemetry against the deployed app. Do not copy a deployed connection string into local configuration or into a bundle you promote to another stage.
The connection string identifies where telemetry goes. It grants no read access, so it can ship to the browser — but anyone can copy it and send data to it, so sample, review ingestion volume, and never treat a client event as proof of a business transaction.
Install the browser SDK
Install @microsoft/rayfin-telemetry at your Rayfin version, with its pinned peer dependencies at exactly these versions:
npm install @microsoft/rayfin-telemetry@2.0.0 @microsoft/opentelemetry-browser@0.1.0-beta.2 @opentelemetry/api@1.9.1 @opentelemetry/api-logs@0.222.0 @opentelemetry/resources@2.11.0In a Universal App project, run it from the project root with -w @rayfin-app/frontend. @microsoft/rayfin-client is a peer dependency too; your app already has it. See the @microsoft/rayfin-telemetry reference for the full API.
Initialize browser telemetry
Create the client from resolved runtime configuration, so rayfinClient.runtimeConfig carries the connection string:
import { RayfinClient, resolveRayfinConfig } from '@microsoft/rayfin-client';
import { browserSession } from '@microsoft/rayfin-auth';
import { dataService } from '@microsoft/rayfin-data';
import type { AppSchema } from '../../rayfin/data/schema';
const resolved = await resolveRayfinConfig({
apiUrl: import.meta.env.VITE_RAYFIN_API_URL,
publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});
export const rayfinClient = RayfinClient.create({
baseUrl: resolved.baseUrl!,
publishableKey: resolved.publishableKey!,
runtimeConfig: resolved.runtimeConfig,
auth: browserSession({ storage: true }),
services: { data: dataService<AppSchema>() },
});
export type AppClient = typeof rayfinClient;Wrap initTelemetry() in one module, with a smoke-test helper for verification:
import { initTelemetry } from '@microsoft/rayfin-telemetry/browser';
import { logs } from '@opentelemetry/api-logs';
import { rayfinClient } from './services/rayfinClient';
const SERVICE_NAME = 'contoso-orders-frontend';
let telemetry: Awaited<ReturnType<typeof initTelemetry>>;
/** Start browser telemetry once per page, after any consent your app requires. */
export async function startTelemetry(): Promise<void> {
telemetry = await initTelemetry({
runtimeConfig: rayfinClient.runtimeConfig,
serviceName: SERVICE_NAME,
});
}
/** Emit one synthetic event to verify ingestion. Never call it on every render. */
export async function sendSmokeTest(): Promise<void> {
if (!telemetry) return;
const { workspaceId, itemId } = rayfinClient.runtimeConfig ?? {};
logs.getLogger(SERVICE_NAME).emit({
eventName: 'observability.smoke_test',
attributes: {
'test.synthetic': true,
...(workspaceId ? { 'fabric.workspace.id': workspaceId } : {}),
...(itemId ? { 'fabric.item.id': itemId } : {}),
},
});
await telemetry.forceFlush();
}Start it from the browser entry point, outside React render and effects, before code that emits telemetry runs:
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App';
import { startTelemetry } from './telemetry';
try {
await startTelemetry();
} catch (error) {
console.error('Browser telemetry did not start.', error);
}
createRoot(document.getElementById('root')!).render(
<StrictMode>
<App />
</StrictMode>,
);If your app needs consent before it collects telemetry, call startTelemetry() after consent instead. In a Universal App, the client already resolves runtime configuration: pass (await getRayfinClient()).runtimeConfig from packages/frontend/src/lib/rayfin-client.ts instead of creating another client.
initTelemetry() behaves this way:
- Without a connection string, it logs
Observability is not configured for this deployment; browser telemetry is off.and resolvesundefined. - It creates one instance per page. Later calls, including from React Strict Mode or hot reload, reuse it and ignore new options; a call with a different connection string, workspace, or item rejects until the page reloads.
- If the SDK fails to initialize, the promise rejects, and a later call can retry.
- It collects page views and keeps sessions and SDK-managed user context, with 100% sampling. It adds no Fetch/XHR, console, or error instrumentation.
Verify with a test event
Call sendSmokeTest() once in the deployed app — for example, from a temporary button — then check each stage:
-
Transport. In the browser network panel, look for a
POSTto the ingestion endpoint ending in/v2/track, and check its status and response. A finishedforceFlush()is not proof of ingestion. -
Ingestion. Allow for ingestion delay, then query the event:
npx rayfin telemetry query "customEvents | where name == 'observability.smoke_test' | project timestamp, name, customDimensions | order by timestamp desc | take 20" --timespan PT1H --max-rows 20 --json -
Association. Check that
customDimensionscontains thefabric.workspace.idandfabric.item.idof the app you deployed.
The named log record arrives in customEvents; page views arrive in pageViews. An empty successful result means no matching rows yet — not proof that emission or ingestion worked or failed.
Query telemetry
npx rayfin telemetry query "pageViews | project timestamp, name, duration | order by timestamp desc | take 20" --timespan PT1HPass the whole KQL query as one quoted argument. Rayfin queries the Application Insights resource allocated to the active deployment — not its backing Log Analytics workspace — so use Application Insights table and column names: traces, customEvents, pageViews, exceptions, requests, and dependencies, with columns such as timestamp, name, message, customDimensions, and duration. You cannot point the command at another resource.
| Option | Description |
|---|---|
--timespan <duration> | ISO 8601 duration limiting the query window, such as PT1H. |
--max-rows <count> | Maximum rows to return, from 1 to 10,000. |
--json | Return one JSON object with status, count, and rows. |
--output <mode> | interactive, plain, or json. |
Without JSON output, each row prints as one JSON object per line. A row limit does not cap query cost; keep a time filter in every query. See rayfin telemetry for error codes.
Investigate an issue
Before reading results, know what the app collects. With the defaults above:
| Question | Table | Collected by default? |
|---|---|---|
| Which pages were visited? | pageViews | Yes, after initTelemetry() runs. |
| Did a business event happen? | customEvents | Only events your code emits. |
| Were there error-level logs? | traces | Only logs your code emits. |
| Did browser exceptions occur? | exceptions | No. |
| Did outgoing HTTP calls fail? | dependencies | No. |
| Did server requests fail? | requests | Not from the browser SDK. |
Pick a narrow UTC window around the symptom, discover columns and event names before you filter on them, then run bounded queries:
customEvents
| where timestamp >= ago(1h)
| summarize observedRecords = count() by name
| top 20 by observedRecords desctraces
| where timestamp >= ago(1h) and severityLevel >= 3
| project timestamp, severityLevel, message, operation_Id, session_Id
| order by timestamp desc
| take 50Severity levels 3 and 4 are Error and Critical. To follow one operation, copy a non-empty operation_Id from a result:
union withsource=signal pageViews, customEvents, traces
| where timestamp >= ago(1h)
| where operation_Id == '<observed-operation-id>'
| project timestamp, signal, name, message, operation_Id, session_Id
| order by timestamp asc
| take 100Use <table> | getschema to list a table's columns. An empty result means no matching collected records, not that the app is healthy; report what the current collection cannot show. Do not enable extra instrumentation or redeploy only to make an investigation pass — review volume and privacy first.
Functions telemetry
When Functions and telemetry are both enabled, rayfin up reconciles the deployed functions' telemetry destination with the app's Application Insights resource. Browser initialization does not configure function logging, and the setting alone does not establish which signals the functions emit — query requests or traces to confirm before you rely on them. When you disable telemetry, the functions' default telemetry configuration is restored before the resource is deleted.
Disable telemetry
Warning
The next rayfin up after disabling deletes the app's Application Insights resource. Telemetry collected in it is no longer available, and re-enabling creates a new, empty resource.
npx rayfin telemetry disable
npx rayfin up --dry-run
npx rayfin updisable sets services.telemetry.enabled: false and warns about the deletion; if telemetry is already off or not configured, nothing changes. After the deployment, the served rayfin.config.json no longer contains a connection string. Pages that are already open keep their SDK and connection string until they reload or call shutdown() on the handle, so also remove or gate the initTelemetry() call.
Before production
- Consent. Initialize only in the browser, after any consent your app requires.
- Sampling. Pick a
samplingPercentagebetween 0 and 100 for your volume budget; the 100% default is for validation. Page views and events consume ingestion volume. Confirm the ingestion quota, retention, and cost of the managed resource for your environment; these docs do not state them. - Privacy. Use fixed event names and reviewed attributes. Never emit tokens, user content, emails, or request bodies. This SDK version also tries to send its own statistics to
https://data.stats.monitor.azure.com/v2/track, separately from your app's resource. - Network. Allow the ingestion host in your Content Security Policy
connect-src. - Browser storage. The SDK buffers unsent telemetry in
sessionStorage; passstorage: { enabled: false }toinitTelemetry()if that is not approved.
Troubleshooting
| Symptom | Fix |
|---|---|
telemetry is not a known command | Upgrade every Rayfin package, including the CLI, to 2.0.0. The commands need no feature flag. |
enable succeeded but the served rayfin.config.json has no connection string | Deploy with rayfin up; enable only edits rayfin.yml. If it is still missing, ask your Fabric environment operator to confirm telemetry enablement and server-written runtime configuration for the workspace. |
initTelemetry() warns that Observability is not configured | The client has no connection string. Create it with runtimeConfig from resolveRayfinConfig(), and test the deployed app rather than npm run dev. |
initTelemetry() warns that new options are ignored | Only the first initialization on a page counts. Reload the page to change options. |
initTelemetry() rejects for another destination, or after shutdown | Reload the page. Do not start a second SDK instance. |
No /v2/track request appears | Check that startTelemetry() ran before the event, the handle is not shut down, and sampling is not 0. |
Requests go to /v1/traces or /v1/logs | An OTLP exporter is pointed at Application Insights. Use the built-in Azure Monitor exporter through initTelemetry(). |
| Ingestion returns 400 | Use the full allocated connection string, not a workspace ID, resource ID, publishable key, or bare instrumentation key. |
| Ingestion returns 401 or 403, or the browser blocks the request | Check the resource's ingestion policy, your CSP connect-src, and network restrictions. Never publish a privileged credential to work around them. |
DEPLOYMENT_NOT_CONFIGURED | Deploy with rayfin up, or switch to the intended deployment. |
AUTHENTICATION_REQUIRED | Run npx rayfin login and retry. |
TELEMETRY_QUERY_FAILED with FEATURE_NOT_ENABLED | Service-side telemetry is off for the workspace. Ask your Fabric environment operator. |
TELEMETRY_QUERY_FAILED with TELEMETRY_NOT_ENABLED | Enable telemetry and deploy before querying. |
TELEMETRY_QUERY_FAILED with TELEMETRY_QUERY_UNAVAILABLE | The resource or query adapter is missing. Redeploy with rayfin up and check for provisioning failures. |
| Permission denied when querying | Confirm you have Write permission on the app item. |
| A query succeeds with no rows | Check the time window, table and column names, the exact event name, sampling, and ingestion delay. |
When you ask for help, include the CLI and package versions, the workspace and item IDs, the UTC time window, and the error code and request ID from the CLI. Leave out credentials and customer data.
Observability and CLI usage telemetry
Observability is your app's telemetry, sent to your app's resource. The Rayfin CLI separately reports anonymous usage data about its own commands; RAYFIN_TELEMETRY_OPTOUT=1 turns that off and has no effect on Observability. See Telemetry.
In my Rayfin 2.0 project, set up Observability for the deployed Fabric app.
1. Run `npx rayfin telemetry enable` and confirm rayfin/rayfin.yml has services.telemetry.enabled: true. Never put a connection string or resource ID in rayfin.yml.
2. Show me the output of `npx rayfin up --dry-run`, and run `npx rayfin up` only after I approve the target workspace.
3. In the frontend package, install @microsoft/rayfin-telemetry@2.0.0 and its exact peer versions: @microsoft/opentelemetry-browser@0.1.0-beta.2, @opentelemetry/api@1.9.1, @opentelemetry/api-logs@0.222.0, and @opentelemetry/resources@2.11.0.
4. Make sure the existing Rayfin client is created with RayfinClient.create and the runtimeConfig returned by resolveRayfinConfig(). Reuse that client; do not create a second one.
5. Add a browser-only startup call to initTelemetry({ runtimeConfig: client.runtimeConfig, serviceName: '<app-name>-frontend' }) from @microsoft/rayfin-telemetry/browser, outside React render and effects and after any consent the app requires. Keep the defaults: no Fetch/XHR, console, or error instrumentation.
6. Add a temporary validation path that emits one 'observability.smoke_test' log record with logs.getLogger(...).emit from @opentelemetry/api-logs and then awaits forceFlush() on the handle.
7. After I trigger it in the deployed app, run `npx rayfin telemetry query "customEvents | where name == 'observability.smoke_test' | project timestamp, name, customDimensions | order by timestamp desc | take 20" --timespan PT1H --max-rows 20 --json` and report the result.
Never run `npx rayfin telemetry disable`: deploying after it deletes the Application Insights resource and its history.Investigate this problem in my deployed Rayfin app using its Application Insights telemetry: <describe the symptom and when it happened, in UTC>.
Use only `npx rayfin telemetry query "<KQL>" --timespan <ISO 8601 duration> --max-rows 100 --json`, passing each query as one quoted argument. Use Application Insights tables (pageViews, customEvents, traces, exceptions, requests, dependencies), not Log Analytics workspace tables.
1. Confirm the active deployment with `npx rayfin up status`, and choose a narrow UTC window around the symptom.
2. Find out what the app collects: read its initTelemetry call and any code that emits log records or events. By default only page views and explicitly emitted events are collected — no exceptions, console logs, Fetch/XHR dependencies, or incoming requests.
3. Discover columns with `<table> | getschema` and event names or customDimensions keys before filtering on them. Never assume a name or key exists.
4. Run bounded queries (a timestamp filter and take) for the relevant tables, and correlate rows only by a non-empty operation_Id or session_Id copied from results.
5. Report the window, the queries, the observed counts, and the findings the rows support, separately from hypotheses and from what current collection cannot show. An empty result is not proof the app is healthy.
Do not add instrumentation, change the telemetry destination, redeploy, or run `rayfin telemetry disable` without asking me.