[DRAFT] Add SDK v2 telemetry core

[bmehta001]

Summary

• Introduces the core SDK v2 telemetry abstractions and typed telemetry payloads.
• Wires 1DS upload plumbing, invocation context/correlation IDs, model/session/action events, catalog/download/EP telemetry, and app session IDs.

Notes

• Draft split from the larger telemetry branch.
• Follow-up hardening/packaging fixes are stacked separately.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
foundry-local	Ready	Preview, Comment	Jul 21, 2026 3:42pm

[Copilot]

Pull request overview

Adds SDK v2 telemetry infrastructure, 1DS transport, correlation contexts, and instrumentation across inference, downloads, catalogs, EP registration, and HTTP services.

Changes:

• Introduces typed telemetry payloads, trackers, metadata, and optional 1DS upload support.
• Instruments SDK operations and streaming HTTP routes with correlated telemetry.
• Adds telemetry dependencies, build options, tests, and linker-size optimizations.

Reviewed changes

Copilot reviewed 49 out of 49 changed files in this pull request and generated 20 comments.

Show a summary per file

File	Description
sdk_v2/cpp/vcpkg.json	Adds telemetry dependencies and feature.
sdk_v2/cpp/test/internal_api/web_service_test.cc	Tests HTTP telemetry behavior.
sdk_v2/cpp/test/internal_api/telemetry_test.cc	Updates telemetry unit tests.
sdk_v2/cpp/test/internal_api/null_telemetry.h	Updates no-op test sink.
sdk_v2/cpp/src/telemetry/telemetry.h	Defines telemetry API and payloads.
sdk_v2/cpp/src/telemetry/telemetry.cc	Maps actions and statuses.
sdk_v2/cpp/src/telemetry/telemetry_metadata.h	Declares process metadata.
sdk_v2/cpp/src/telemetry/telemetry_metadata.cc	Collects platform metadata.
sdk_v2/cpp/src/telemetry/telemetry_logger.h	Expands local telemetry logger.
sdk_v2/cpp/src/telemetry/telemetry_logger.cc	Formats typed telemetry events.
sdk_v2/cpp/src/telemetry/telemetry_environment.h	Declares runtime telemetry gating.
sdk_v2/cpp/src/telemetry/telemetry_environment.cc	Implements CI/test detection.
sdk_v2/cpp/src/telemetry/telemetry_action_tracker.h	Adds invocation-context tracking.
sdk_v2/cpp/src/telemetry/telemetry_action_tracker.cc	Emits correlated action events.
sdk_v2/cpp/src/telemetry/one_ds_tenant_token.h.in	Generates the tenant-token header.
sdk_v2/cpp/src/telemetry/one_ds_telemetry.h	Declares the 1DS sink.
sdk_v2/cpp/src/telemetry/one_ds_telemetry.cc	Implements 1DS event uploads.
sdk_v2/cpp/src/telemetry/invocation_context.h	Defines correlation context.
sdk_v2/cpp/src/telemetry/invocation_context.cc	Generates correlation UUIDs.
sdk_v2/cpp/src/telemetry/ep_download_tracker.h	Declares EP telemetry tracker.
sdk_v2/cpp/src/telemetry/ep_download_tracker.cc	Emits EP attempt details.
sdk_v2/cpp/src/telemetry/download_tracker.h	Declares model-download tracker.
sdk_v2/cpp/src/telemetry/download_tracker.cc	Emits model-download telemetry.
sdk_v2/cpp/src/service/web_service.cc	Instruments status and unmatched routes.
sdk_v2/cpp/src/service/responses_handler.h	Passes streaming route trackers.
sdk_v2/cpp/src/service/responses_handler.cc	Instruments Responses API operations.
sdk_v2/cpp/src/service/models_handlers.cc	Instruments model endpoints.
sdk_v2/cpp/src/service/handler_utils.h	Extracts request user agents.
sdk_v2/cpp/src/service/embeddings_handler.cc	Instruments embedding inference.
sdk_v2/cpp/src/service/chat_completions_handler.h	Extends streaming tracker ownership.
sdk_v2/cpp/src/service/chat_completions_handler.cc	Instruments chat streaming.
sdk_v2/cpp/src/service/audio_transcriptions_handler.h	Extends audio tracker ownership.
sdk_v2/cpp/src/service/audio_transcriptions_handler.cc	Instruments audio streaming.
sdk_v2/cpp/src/manager.h	Adjusts telemetry lifetime ordering.
sdk_v2/cpp/src/manager.cc	Constructs sinks and manages sessions.
sdk_v2/cpp/src/inferencing/session/session.h	Adds per-request telemetry context.
sdk_v2/cpp/src/inferencing/session/session.cc	Emits inference usage metrics.
sdk_v2/cpp/src/ep_detection/ep_detector.h	Accepts an optional telemetry sink.
sdk_v2/cpp/src/ep_detection/ep_detector.cc	Instruments EP registration.
sdk_v2/cpp/src/download/download_manager.h	Extends download telemetry API.
sdk_v2/cpp/src/download/download_manager.cc	Instruments model downloads.
sdk_v2/cpp/src/download/blob_downloader.h	Defines download statistics.
sdk_v2/cpp/src/download/blob_downloader.cc	Collects transfer statistics.
sdk_v2/cpp/src/catalog/catalog_client.h	Extends catalog telemetry API.
sdk_v2/cpp/src/catalog/catalog_client.cc	Emits catalog-fetch events.
sdk_v2/cpp/src/catalog/azure_model_catalog.h	Stores the telemetry sink.
sdk_v2/cpp/src/catalog/azure_model_catalog.cc	Adds catalog URL dimensions.
sdk_v2/cpp/CMakeLists.txt	Configures 1DS and linker stripping.
sdk_v2/cpp/build.py	Adds telemetry build options.

Comments suppressed due to low confidence (1)

sdk_v2/cpp/src/service/responses_handler.cc:605

• Calling Remove() makes shutdown stop waiting for this worker, but the captured route_tracker is destroyed only after the lambda returns. Manager teardown can consequently destroy telemetry in that gap and the tracker destructor will dereference freed telemetry. Emit/destroy the tracker before untracking the thread.

    // Terminal event per spec
    body_ptr->Push("data: [DONE]\n\n");
    body_ptr->Finish();

    tracker.Remove(std::this_thread::get_id());

[Copilot]

Pull request overview

Copilot reviewed 49 out of 49 changed files in this pull request and generated 13 comments.

[Copilot]

Pull request overview

Copilot reviewed 49 out of 49 changed files in this pull request and generated 11 comments.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

sdk_v2/cpp/src/telemetry/one_ds_telemetry.cc:180

• A zero teardown timeout makes cpp-client-telemetry skip the upload-wait path and abort queued/pending requests during FlushAndTeardown(). Since the destructor relies on that call to deliver the final session and recently queued events, normal process shutdown can lose telemetry. Use a positive timeout (the upstream runtime default is 1 second; its functional tests commonly use 2 seconds).

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

sdk_v2/cpp/src/manager.cc:354

• disable_telemetry=true still installs a telemetry sink: OneDsTelemetry mirrors every event to TelemetryLogger, and the no-1DS branch always uses TelemetryLogger directly. Consequently model IDs, user agents, timings, and errors continue to be collected in local logs even though every public configuration contract says the SDK “collects and uploads nothing.” Select a no-op ITelemetry implementation when the option is set (before passing it to the detector, catalog, downloads, and sessions); keep local mirroring only for CI/transport-unavailable cases where telemetry was not explicitly disabled.

#if FOUNDRY_LOCAL_HAS_1DS
  // OneDsTelemetry keeps an always-on local diagnostic mirror and uploads to 1DS only when telemetry is
  // not disabled by configuration and not in a CI environment.
  telemetry_ = std::make_unique<OneDsTelemetry>(config_.app_name, *logger_, config_.disable_telemetry);
#else
  telemetry_ = std::make_unique<TelemetryLogger>(config_.app_name, *logger_);
#endif

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

sdk_v2/cpp/src/manager.cc:353

• disable_telemetry does not implement the documented “collects and uploads nothing” contract. OneDsTelemetry still sends every event to its TelemetryLogger mirror when disabled, while telemetry-off builds unconditionally select TelemetryLogger and ignore the flag entirely. Select a true no-op sink before wiring telemetry into the subsystems, and verify that disabling telemetry emits neither event payloads nor telemetry log records.

#if FOUNDRY_LOCAL_HAS_1DS
  // OneDsTelemetry keeps an always-on local diagnostic mirror and uploads to 1DS only when telemetry is
  // not disabled by configuration and not in a CI environment.
  telemetry_ = std::make_unique<OneDsTelemetry>(config_.app_name, *logger_, config_.disable_telemetry);
#else
  telemetry_ = std::make_unique<TelemetryLogger>(config_.app_name, *logger_);

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

sdk_v2/cpp/CMakeLists.txt:241

• These telemetry sources are compiled for every WIN32 target even though only the 1DS dependency is disabled for WindowsStore. device_id.cc and telemetry_metadata.cc still compile desktop-only APIs such as RegCreateKeyExA, GetFileVersionInfoA, and GlobalMemoryStatusEx, so UWP builds can fail or fail app certification. Gate/provide UWP implementations for the core telemetry sources as well as disabling 1DS.

    src/service/audio_transcriptions_handler.cc
    src/service/embeddings_handler.cc
    src/service/chat_completions_handler.cc
    src/service/models_handlers.cc
    src/service/responses_handler.cc
    src/service/web_service.cc
    src/telemetry/telemetry.cc
    src/telemetry/telemetry_action_tracker.cc
    src/telemetry/device_id.cc

sdk_v2/cpp/src/ep_detection/ep_detector.cc:269

• On every successful combined DownloadAndRegister call this reports the download phase as Skipped, even when the bootstrapper actually downloaded a package. That makes DownloadStatus/DownloadTimeMs inaccurate for the main success path. The bootstrapper result needs to expose whether download occurred (and its timing/status), or this event should report only an aggregate phase that can be measured correctly.

        tracker->RecordDownloadComplete(ActionStatus::kSkipped,
                                        was_registered_before ? "Registered" : "Unknown");
        tracker->RecordRegisterComplete(ActionStatus::kSuccess, "Registered");

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

sdk_v2/cpp/src/telemetry/telemetry_metadata.cc:85

• needed includes the terminating NUL because the input length is -1, but out reserves only needed - 1 bytes while the conversion is allowed to write needed. On Windows this writes one byte past the string buffer whenever a host version is found. Allocate space for the terminator, then remove it after conversion.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (4)

sdk_v2/cpp/src/telemetry/telemetry_metadata.cc:84

• needed includes the terminating NUL, but out reserves only needed - 1 bytes while WideCharToMultiByte is told it can write needed. On Windows this writes one byte past the string's size whenever an EXE version string is found. Allocate needed bytes; TrimVersionString will remove the trailing NUL.
  sdk_v2/cpp/docs/Privacy.md:17
• The “What is collected” disclosure is incomplete relative to the upload implementation: ProcessInfo sends the process name and locale, common context sends the configured app name, action events send the HTTP User-Agent, and audio events can send the request language. Please disclose these fields (or stop uploading them) so this privacy document accurately describes the telemetry payload.

- **Environment / device:** Foundry Local version, operating system, architecture, CPU details, and total memory, plus a device identifier. On Windows, Linux, and macOS the device identifier is a locally generated random UUID (**not** a hardware identifier such as a machine GUID); only a hashed form is transmitted, and it can be reset. On Android, Foundry Local uses the device identifier provided by the 1DS SDK instead of creating a separate Foundry-generated device id.

sdk_v2/cpp/CMakeLists.txt:311

• The newly compiled Windows device-ID implementation directly calls OpenProcessToken, GetTokenInformation, RegGetValueA, and RegCreateKeyExA, all of which require Advapi32.lib. It is compiled even when FOUNDRY_LOCAL_USE_TELEMETRY=OFF, so a no-telemetry Windows build cannot rely on the 1DS target to supply that library and will fail with unresolved externals.

        target_link_libraries(${TARGET} ${LINK_SCOPE} dbghelp bcrypt version)

sdk_v2/cpp/CMakeLists.txt:52

• Turning off the 1DS transport is not sufficient to keep UWP buildable: device_id.cc and telemetry_metadata.cc are still compiled unconditionally and their _WIN32 branches use desktop-only registry/token/version APIs (RegGetValueA, OpenProcessToken, GetFileVersionInfoA). Add a WindowsStore-safe implementation or exclude those helpers and their Manager startup calls for UWP; otherwise the explicitly supported UWP configuration fails before the transport setting matters.

if(CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
    set(FOUNDRY_LOCAL_USE_TELEMETRY OFF CACHE BOOL "1DS telemetry is not available for UWP" FORCE)
endif()

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

sdk_v2/cpp/src/telemetry/telemetry_metadata.cc:84

• needed includes the terminating NUL, but out has only needed - 1 writable characters while the conversion is told it may write needed. This writes past the string's size on every successful Windows version lookup. Allocate needed, then remove the terminator after conversion.
  sdk_v2/cpp/include/foundry_local/foundry_local_c.h:934
• Appending this function to the version-1 table without incrementing FOUNDRY_LOCAL_API_VERSION defeats the ABI version check. The updated C#/Python bindings still request v1, so when they load an older v1 native library they marshal/read this new slot past the old table and may call an arbitrary pointer instead of getting a clean version-mismatch failure. Introduce API v2 (and update each binding's requested version), while retaining the v1 table for older consumers.

  /// Optional. Disable all telemetry. When true, the SDK collects and uploads no telemetry (no 1DS
  /// uploader is created and no device identifier is written). Defaults to false (telemetry enabled).
  FL_API_STATUS(SetDisableTelemetry, _In_ flConfiguration* config, bool disable);

sdk_v2/cpp/src/util/sha256.cc:87

• The only new assertion for this path checks the c: prefix and output length, so both platform implementations could return an incorrect 64-character digest undetected. Add Sha256String known-vector tests (including "abc" and the empty string), matching the existing Sha256File vectors in sha256_test.cc.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (4)

sdk_v2/cpp/CMakeLists.txt:311

• The new Windows device-ID implementation calls OpenProcessToken, RegGetValueA, and RegCreateKeyExA, all of which require Advapi32.lib. This target does not link it, so Windows builds—especially the newly supported --no_telemetry configuration where MSTelemetry cannot supply a transitive dependency—fail with unresolved externals.

        target_link_libraries(${TARGET} ${LINK_SCOPE} dbghelp bcrypt version)

sdk_v2/cpp/CMakeLists.txt:52

• Turning off 1DS is not sufficient to keep the WindowsStore build valid. device_id.cc and telemetry_metadata.cc are still compiled unconditionally and their _WIN32 branches call desktop-only registry and file-version APIs (RegGetValueA/RegCreateKeyExA and GetFileVersionInfoA). The UWP configuration therefore still compiles/links unsupported APIs; add WindowsStore-safe implementations or exclude these startup metadata paths for UWP.

if(CMAKE_SYSTEM_NAME STREQUAL "WindowsStore")
    set(FOUNDRY_LOCAL_USE_TELEMETRY OFF CACHE BOOL "1DS telemetry is not available for UWP" FORCE)
endif()

sdk_v2/cpp/src/ep_detection/ep_detector.cc:269

• RecordDownloadComplete is called only after the combined DownloadAndRegister operation has finished. Because that method measures elapsed time since RecordInitialState, the full operation is reported as a skipped download, while the immediately following successful register phase is reported as approximately 0 ms. Move the skipped download transition before invoking the combined bootstrapper so its elapsed time is attributed to registration.

        tracker->RecordDownloadComplete(ActionStatus::kSkipped,
                                        was_registered_before ? "Registered" : "Unknown");
        tracker->RecordRegisterComplete(ActionStatus::kSuccess, "Registered");

sdk_v2/cpp/src/ep_detection/ep_detector.cc:281

• This failure path has the same phase-timing inversion: despite the comment saying the combined operation is recorded as registration, calling RecordDownloadComplete after it returns puts all elapsed time in download_duration_ms with status Skipped, then records a near-zero failed registration. Advance to the register stage before calling the bootstrapper.

        // Record the combined operation as the register phase rather than fabricating a download/register split.
        tracker->RecordDownloadComplete(ActionStatus::kSkipped,
                                        was_registered_before ? "Registered" : "Unknown");
        tracker->RecordRegisterComplete(ActionStatus::kFailure,
                                        was_registered_before ? "Registered" : "Unknown");

[Copilot]

Pull request overview

Copilot reviewed 85 out of 85 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

sdk_v2/python/src/foundry_local_sdk/_native/build_cffi.py:477

• cffi’s cdef parser does not accept the C bool spelling (the file’s preprocessing contract at line 46 explicitly requires _Bool). This new vtable member therefore prevents _cffi_bindings from being generated; use _Bool to match the other boolean ABI declarations.
  sdk_v2/cpp/src/telemetry/one_ds_telemetry.cc:218
• This flag is set too late: if GetLogger returns null or throws, the successfully created provider is never torn down/released (the null path drops an Impl containing only a raw manager pointer, and the catch sees this flag as false). Mark initialization immediately after CreateLogManager succeeds and release the provider on the null-logger path.