Skip to content

Conversation

@Almaju
Copy link
Contributor

@Almaju Almaju commented Nov 28, 2025

Telemetry Architecture

Core Telemetry Trait

A generic Telemetry<A> trait at the core/std layer:

  • Simple: single record(&self, event: &A) method
  • Generic: works with any event type
  • Dependency-free: modules depend only on the trait, not implementations
  • Minimal coupling: each module records only what it needs

Super Traits for Complex Components

Higher-level traits compose multiple telemetry types:

  • MARSTelemetry: Requires Telemetry<CacheOutcome> + Telemetry<serde_json::Error>
  • AdsTelemetry: Composes MARSTelemetry + specific error types (RequestAdsError, RecordClickError, etc.) + ClientOperationEvent

This provides granular control without coupling modules to specific implementations.

FFI Layer: Platform-Specific Implementations

The MozAdsTelemetry trait is exposed via UniFFI for iOS/Android:

  • Platform-specific: devices implement it with their own Glean code
  • Glean-ready: methods map directly to Glean metrics (labels/values)
  • Passed at construction: injected via MozAdsClientConfig
  • Wrapped: MozAdsTelemetryWrapper bridges FFI trait to core telemetry traits

Benefits

  • Clean separation: Core logic is independent of FFI/platform concerns
  • Granular control: Each module records only relevant events
  • Trait composition: Super traits express requirements without implementation details
  • Platform flexibility: Each platform implements telemetry with its own Glean integration
  • No dependency bloat: Core modules don't depend on FFI or platform-specific code

This keeps the core clean and flexible while enabling platform-specific telemetry integration.

Pull Request checklist

  • Breaking changes: This PR follows our breaking change policy
    • This PR follows the breaking change policy:
      • This PR has no breaking API changes, or
      • There are corresponding PRs for our consumer applications that resolve the breaking changes and have been approved
  • Quality: This PR builds and tests run cleanly
    • Note:
      • For changes that need extra cross-platform testing, consider adding [ci full] to the PR title.
      • If this pull request includes a breaking change, consider cutting a new release after merging.
  • Tests: This PR includes thorough tests or an explanation of why it does not
  • Changelog: This PR includes a changelog entry in CHANGELOG.md or an explanation of why it does not need one
    • Any breaking changes to Swift or Kotlin binding APIs are noted explicitly
  • Dependencies: This PR follows our dependency management guidelines
    • Any new dependencies are accompanied by a summary of the due diligence applied in selecting them.

@Almaju Almaju marked this pull request as ready for review December 1, 2025 20:45
@Almaju Almaju force-pushed the ads-client-telemetry branch from a9944b1 to ff2d2c3 Compare December 1, 2025 21:09
@Almaju Almaju marked this pull request as draft December 8, 2025 21:06
@Almaju Almaju force-pushed the ads-client-telemetry branch from 623ba56 to 3d6650d Compare December 9, 2025 22:37
@Almaju Almaju marked this pull request as ready for review December 9, 2025 23:11
@Almaju Almaju force-pushed the ads-client-telemetry branch from 3d6650d to 690f211 Compare December 9, 2025 23:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant