Skip to content

Minimal observability metrics (relay & client) #853

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
fcancela wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Minimal observability metrics (relay & client) #853

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
523fcc2
moq-lite: add optional Stats hooks; moq-native accept_with_stats
fcancela Jan 16, 2026
facf788
relay: basic session + app byte counters exposed at /metrics
fcancela Jan 16, 2026
436263d
hang: metrics-only OTLP (connections + startup time)
fcancela Jan 16, 2026
76302df
hang: drop @opentelemetry/resources dependency
fcancela Jan 16, 2026
0082ade
chore: update bun.lock with new OpenTelemetry dependencies and protob…
fcancela Jan 16, 2026
3ec2d84
Update js/hang/src/observability/index.ts
fcancela Jan 16, 2026
0f617b0
observability: optional prom+grafana+otel compose for demo metrics
fcancela Jan 16, 2026
5acf872
just: add observability helper recipes
fcancela Jan 16, 2026
cca8aaf
just: make observability run stack + dev
fcancela Jan 16, 2026
c20b708
chore: update dependencies for OpenTelemetry and clean up observabili…
fcancela Jan 16, 2026
0f68bb2
fix: remove unnecessary newline in observability index and reorder im…
fcancela Jan 16, 2026
2f7a19f
refactor: clean up session and stats imports, format function calls f…
fcancela Jan 16, 2026
41786ff
Merge branch 'main' of https://github.com/qualabs/moq into feat/obser…
fcancela Jan 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions bun.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions deno.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions js/hang/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,9 @@
"@moq/lite": "workspace:^",
"@moq/signals": "workspace:^",
"@libav.js/variant-opus-af": "^6.8.8",
"@opentelemetry/api": "^1.8.0",
"@opentelemetry/sdk-metrics": "^1.25.0",
"@opentelemetry/exporter-metrics-otlp-http": "^0.52.0",
"async-mutex": "^0.5.0",
"comlink": "^4.4.2",
"zod": "^4.1.5"
Expand Down
122 changes: 122 additions & 0 deletions js/hang/src/observability/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
/**
* Minimal OpenTelemetry metrics for MoQ client (browser).
*
* Kept intentionally small for reviewability:
* - `moq_client_connections_total{transport=...}`
* - `moq_client_startup_time_seconds{track_type=...}`
*/

import type { Counter, Histogram, Meter } from "@opentelemetry/api";
import { metrics } from "@opentelemetry/api";
import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";

let initialized = false;
let sessionId: string | undefined;

export interface ObservabilityConfig {
/** OTLP endpoint URL (default: http://localhost:4318) */
otlpEndpoint?: string;
/** Service name (default: moq-client) */
serviceName?: string;
/** Enable observability (default: true if endpoint provided) */
enabled?: boolean;
/** Per-player session id (defaults to a random UUID) */
sessionId?: string;
}

function createSessionId(): string {
try {
return globalThis.crypto?.randomUUID?.() ?? `sid-${Math.random().toString(16).slice(2)}-${Date.now()}`;
} catch {
return `sid-${Math.random().toString(16).slice(2)}-${Date.now()}`;
}
}

export function initObservability(config: ObservabilityConfig = {}): void {
if (initialized) return;

const endpoint = config.otlpEndpoint || "http://localhost:4318";
const serviceName = config.serviceName || "moq-client";
const enabled = config.enabled ?? !!config.otlpEndpoint;
sessionId = config.sessionId || createSessionId();

if (!enabled) return;

const exporterHeaders = { "Content-Type": "application/json" };
const metricExporter = new OTLPMetricExporter({
url: `${endpoint}/v1/metrics`,
headers: exporterHeaders,
});

const reader = new PeriodicExportingMetricReader({
exporter: metricExporter,
exportIntervalMillis: 10000,
});

const meterProvider = new MeterProvider({
readers: [reader],
});

metrics.setGlobalMeterProvider(meterProvider);
const meter = metrics.getMeter(serviceName);

clientMetricsInstance = new ClientMetrics(meter);
setupConnectionTracking();
initialized = true;
}

function setupConnectionTracking() {
// Dynamically import to avoid circular deps.
import("@moq/lite")
Comment on lines +70 to +71
Copy link
Collaborator

@kixelated kixelated Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

?

.then((Moq) => {
if (Moq.Connection?.onConnectionType) {
Moq.Connection.onConnectionType((type: "webtransport" | "websocket") => {
getClientMetrics()?.recordConnection(type);
});
}
})
.catch((error) => console.warn("Failed to set up connection tracking for observability:", error));
}

export class ClientMetrics {
private connectionCounter?: Counter;
private startupTimeHistogram?: Histogram;

constructor(meter?: Meter) {
if (meter) {
this.connectionCounter = meter.createCounter("moq_client_connections_total", {
description: "Total client connections by transport type",
});

this.startupTimeHistogram = meter.createHistogram("moq_client_startup_time_seconds", {
description: "Time to first audio/video frame in seconds",
unit: "s",
});
}
}

recordConnection(transportType: "webtransport" | "websocket"): void {
const attrs: Record<string, string> = { transport: transportType };
if (sessionId) attrs["moq.player.session_id"] = sessionId;
this.connectionCounter?.add(1, attrs);
}

recordStartupTime(seconds: number, attributes?: Record<string, string>): void {
const attrs: Record<string, string> = { ...(attributes ?? {}) };
if (sessionId) attrs["moq.player.session_id"] = sessionId;
this.startupTimeHistogram?.record(seconds, attrs);
}
}

let clientMetricsInstance: ClientMetrics | undefined;

export function getClientMetrics(): ClientMetrics | undefined {
if (!clientMetricsInstance) clientMetricsInstance = new ClientMetrics();
return clientMetricsInstance;
}

export function recordMetric(fn: (metrics: ClientMetrics) => void): void {
const m = getClientMetrics();
if (m) fn(m);
}
13 changes: 13 additions & 0 deletions js/hang/src/watch/audio/source.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import type { Time } from "@moq/lite";
import { Effect, type Getter, Signal } from "@moq/signals";
import type * as Catalog from "../../catalog";
import * as Frame from "../../frame";
import { recordMetric } from "../../observability";
import * as Hex from "../../util/hex";
import * as libav from "../../util/libav";
import type * as Render from "./render";
Expand Down Expand Up @@ -163,6 +164,10 @@ export class Source {
const active = effect.get(this.active);
if (!active) return;

// Track time-to-first-audio
const trackStartTime = performance.now();
let firstFrameDecoded = false;

const sub = broadcast.subscribe(active, catalog.priority);
effect.cleanup(() => sub.close());

Expand Down Expand Up @@ -195,6 +200,14 @@ export class Source {
const frame = await consumer.decode();
if (!frame) break;

// Record time-to-first-audio
if (!firstFrameDecoded) {
firstFrameDecoded = true;
const ttfaSeconds = (performance.now() - trackStartTime) / 1000;
recordMetric((m) => m.recordStartupTime(ttfaSeconds, { codec: config.codec, track_type: "audio" }));
console.log(`[Audio] Time-to-first-audio: ${(ttfaSeconds * 1000).toFixed(0)}ms`);
}

this.#stats.update((stats) => ({
bytesReceived: (stats?.bytesReceived ?? 0) + frame.data.byteLength,
}));
Expand Down
Loading
Loading