Introduction

When you put a realtime avatar behind a voice agent, the debugging surface gets bigger fast. You are no longer just tracing text prompts and LLM calls. You also need to understand WebRTC session setup, media timing, avatar rendering, audio quality, browser behavior, and the exact point where a user perceives latency or drift. In practice, most teams end up with two complementary sources of truth: client-side logs from the application or browser, and server-side telemetry from the avatar platform.

This post compares those two strategies in the context of a realtime avatar stack. The goal is to help you decide what to log, where to log it, and how to use the data to debug issues like no-video sessions, clipped audio, lip-sync drift, and unexplained quality drops. I’ll also show where Protoface fits in, without assuming you want to instrument everything the same way.

Client logs: what they’re good for

Client-side logs are the fastest way to understand what the user actually experienced. For realtime avatars, that usually means logs from one of three places:

• the browser app embedding the avatar

• a voice-agent runtime using a plugin or SDK

• a mobile or desktop client consuming an embedded session

These logs are especially valuable for issues that happen before the media pipeline is “fully alive.” Examples:

• ICE negotiation stalls

• permission failures for microphone or autoplay

• wrong session IDs or stale tokens

• race conditions in UI state

• rendering problems that only happen in one browser

The main advantage is fidelity. If the avatar looks frozen to the user, client logs can tell you whether the browser never attached a video track, whether the page muted autoplay, or whether the session was established but the UI never subscribed to the right track.

What to log on the client

Keep client logs structured and correlated. Free-form console output is useful during development, but it doesn’t scale for production debugging.

For a realtime avatar app, I would log:

• session creation request ID

• avatar/session identifiers

• signaling or connection state transitions

• media track attach/detach events

• render start time and first-frame time

• user agent and browser version

• any local audio device errors

If you are using a browser embed, also log the parent origin, iframe load time, and the moment the user interacts with the page. For WebRTC-based experiences, a meaningful amount of failure comes from policy constraints rather than backend errors.

const t0 = performance.now();

log("user_clicked_start", { autoplay: navigator.userActivation?.hasBeenActive });

const t0 = performance.now();

log("user_clicked_start", { autoplay: navigator.userActivation?.hasBeenActive });

const t0 = performance.now();

log("user_clicked_start", { autoplay: navigator.userActivation?.hasBeenActive });

This kind of logging is intentionally boring. That’s good. You want a timeline you can diff against server telemetry when something goes wrong.

Server-side telemetry: what it’s good for

Server-side telemetry tells you what the platform saw: session lifecycle events, request metadata, quality-related signals, and the outcome of backend operations. For avatar systems, that usually includes the server’s view of session creation, media negotiation, duration, usage, and failure modes that never surface cleanly to the client.

Telemetry is especially useful when the browser is silent or unhelpful. A client may only know “connection failed,” while the server can show that the session was rejected, rate-limited, expired, or misconfigured. It also helps answer operational questions that client logs cannot answer reliably:

• How many sessions were created per day?

• Which quality tier is being used most?

• Are failures concentrated in one region or one browser family?

• Did session duration drop after a release?

• Are specific API keys producing disproportionate errors?

For developer-facing avatar platforms, telemetry is also the right place to track usage and billing-relevant facts. You generally do not want to infer that from the client, because clients are easy to tamper with and easy to lose when the page reloads.

What to log on the server

Server telemetry should be normalized, low-cardinality, and correlatable. In other words: a lot less chatty than client logs, but much more trustworthy.

At minimum, I’d expect these fields in a realtime avatar system:

• request/session ID

• API key or tenant identifier, ideally anonymized or hashed internally

• avatar ID and session ID

• timestamps for create, connect, active, and end states

• duration

• quality tier

• error class and error code

• origin or integration surface when relevant

If you are debugging drift or performance, the important thing is not raw volume of logs; it is the shape of the lifecycle. For example, a session that starts quickly but ends early may indicate transport instability, while a session that never becomes active may point to auth, configuration, or policy problems.

Server-side telemetry also gives you a cleaner place to detect abusive patterns. That matters for customer-managed embeds where you may enforce parent-origin allowlists, per-IP limits, and session-duration caps. Those controls are easiest to audit centrally.

How to think about correlation

The most useful setup is not “client logs or server telemetry.” It is a shared correlation model across both. Pick one identifier that follows the session from creation through teardown, then attach it to every log record you care about.

A practical flow looks like this:

1. Create a session on the server.

2. Return a session ID and any connection metadata needed by the client.

3. Have the browser or agent runtime log that same session ID.

4. Aggregate server telemetry by session ID, API key, and quality tier.

5. Use timestamps to compare client-perceived latency with server lifecycle timing.

This lets you answer questions like: “Did the avatar take two seconds to connect, or did it connect in 300 ms and the browser only rendered it late?” That distinction matters. One is a backend problem; the other is usually a frontend or media-attachment problem.

Practical trade-offs: noise, privacy, and cost

There are trade-offs in both directions.

Client logs are noisy and can expose sensitive environment details if you are not careful. They are also incomplete: a browser tab can crash, navigate away, or suppress logs. On the other hand, they can capture the exact user agent, device state, and UI timing that server telemetry cannot see.

Server telemetry is more stable and more useful for operational reporting, but it can be too coarse to diagnose visual or timing problems by itself. It may tell you that a session started and ended, but not that the avatar was visible only after the user spoke, or that audio autoplay was blocked until interaction.

For privacy, prefer these habits:

• do not log raw user content unless you need it and have a clear policy

• avoid storing full browser fingerprints

• redact secrets and API keys from client output

• separate diagnostic logs from long-term analytics when possible

For cost, remember that high-cardinality client logs can get expensive quickly. Keep detailed logs behind a sampling or debug flag. Use server telemetry for always-on metrics, and use client logs selectively when reproducing a bug.

Example: API and SDK instrumentation

Here is a minimal pattern for creating a session and logging its ID on the client. The exact request fields depend on your integration and are documented in the API reference.

curl -X POST https://api.protoface.com/v1/sessions \
-d '{"avatar_id":"ava_123"}'

curl -X POST https://api.protoface.com/v1/sessions \
-d '{"avatar_id":"ava_123"}'

curl -X POST https://api.protoface.com/v1/sessions \
-d '{"avatar_id":"ava_123"}'

In Python, the same idea applies: create the session, persist the returned identifier, and attach that ID to every downstream log record.

from protoface import Client

})

from protoface import Client

})

from protoface import Client

})

If you are embedding Protoface in a voice agent stack, the same correlation principle applies to the agent runtime. The plugin should log when the avatar is attached to the agent, when media becomes active, and when the session ends. The underlying runtime may be LiveKit, Pipecat, or another voice orchestration layer; the logging model does not change much.

For examples, the livekit plugin repo is the right place to inspect the integration shape: quickstarts and docs are also helpful if you are comparing agent stacks, but keep your own instrumentation minimal and explicit.

Where Protoface fits

The useful thing about a platform like Protoface is that it gives you both surfaces: browser-facing integration paths and server-side APIs. For a developer-managed avatar workflow, the REST API and Python SDK are the cleanest places to establish session IDs, quality tier, and usage-visible metadata. From there, you can instrument your own app around those identifiers and decide how much detail belongs in client logs versus server telemetry.

If you are using the LiveKit Agents plugin or the Python SDK, the implementation pattern is straightforward: create a session, attach it to your agent or UI, and propagate the returned ID into structured logs on both sides. The docs are the source of truth for exact parameters and response fields: docs.protoface.com. If you want to start from reference code, the SDK repo is here: GitHub.

Conclusion

For realtime avatar apps, client logs and server-side telemetry solve different problems. Client logs explain what the user’s browser or agent runtime experienced. Server telemetry explains what the platform accepted, rejected, measured, and billed. You need both if you want to debug timing, quality, and lifecycle issues with confidence.

A good default is:

• log aggressively on the client during development, then narrow to structured session-level events in production

• log lifecycle and usage events on the server by default

• correlate everything with one session identifier

• treat quality tier and session duration as first-class telemetry fields

If you are implementing this with Protoface, start with the docs, wire correlation IDs through your session create flow, and then decide how much browser-side detail you actually need. That usually gets you to useful debugging faster than trying to centralize every log in one place.