@@ -58,13 +58,93 @@ Configuration for initializing the ads client.
5858pub struct MozAdsClientConfig {
5959 pub environment : Environment ,
6060 pub cache_config : Option <MozAdsCacheConfig >,
61+ pub telemetry : Option <Arc <dyn MozAdsTelemetry >>,
6162}
6263```
6364
64- | Field | Type | Description |
65- | -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
66- | ` environment ` | ` Environment ` | Selects which MARS environment to connect to. Unless in a dev build, this value can only ever be Prod. |
67- | ` cache_config ` | ` Option<MozAdsCacheConfig> ` | Optional configuration for the internal cache. |
65+ | Field | Type | Description |
66+ | -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
67+ | ` environment ` | ` Environment ` | Selects which MARS environment to connect to. Unless in a dev build, this value can only ever be Prod. |
68+ | ` cache_config ` | ` Option<MozAdsCacheConfig> ` | Optional configuration for the internal cache. |
69+ | ` telemetry ` | ` Option<Arc<dyn MozAdsTelemetry>> ` | Optional telemetry instance for recording metrics. If not provided, a no-op implementation is used. |
70+
71+ ---
72+
73+ ## ` MozAdsTelemetry `
74+
75+ Telemetry interface for recording ads client metrics. You must provide an implementation of this interface to the ` MozAdsClientConfig ` constructor to enable telemetry collection. If no telemetry instance is provided, a no-op implementation is used and no metrics will be recorded.
76+
77+ ``` rust
78+ pub trait MozAdsTelemetry : Send + Sync {
79+ fn record_build_cache_error (& self , label : String , value : String );
80+ fn record_client_error (& self , label : String , value : String );
81+ fn record_client_operation_total (& self , label : String );
82+ fn record_deserialization_error (& self , label : String , value : String );
83+ fn record_http_cache_outcome (& self , label : String , value : String );
84+ }
85+ ```
86+
87+ ### Implementing Telemetry
88+
89+ To enable telemetry collection, you need to implement the ` MozAdsTelemetry ` interface and provide an instance to the ` MozAdsClientConfig ` constructor. The following examples show how to bind Glean metrics to the telemetry interface.
90+
91+ #### Swift Example
92+
93+ ``` swift
94+ import MozillaRustComponents
95+ import Glean
96+
97+ public final class AdsClientTelemetry : MozAdsTelemetry {
98+ public func recordBuildCacheError (label String , value String ) {
99+ AdsClientMetrics.buildCacheError [label].set (value)
100+ }
101+
102+ public func recordClientError (label String , value String ) {
103+ AdsClientMetrics.clientError [label].set (value)
104+ }
105+
106+ public func recordClientOperationTotal (label String ) {
107+ AdsClientMetrics.clientOperationTotal [label].add ()
108+ }
109+
110+ public func recordDeserializationError (label String , value String ) {
111+ AdsClientMetrics.deserializationError [label].set (value)
112+ }
113+
114+ public func recordHttpCacheOutcome (label String , value String ) {
115+ AdsClientMetrics.httpCacheOutcome [label].set (value)
116+ }
117+ }
118+ ```
119+
120+ #### Kotlin Example
121+
122+ ``` kotlin
123+ import mozilla.appservices.adsclient.MozAdsTelemetry
124+ import org.mozilla.appservices.ads_client.GleanMetrics.AdsClient
125+
126+ class AdsClientTelemetry : MozAdsTelemetry {
127+ override fun recordBuildCacheError (label : String , value : String ) {
128+ AdsClient .buildCacheError[label].set(value)
129+ }
130+
131+ override fun recordClientError (label : String , value : String ) {
132+ AdsClient .clientError[label].set(value)
133+ }
134+
135+ override fun recordClientOperationTotal (label : String ) {
136+ AdsClient .clientOperationTotal[label].add()
137+ }
138+
139+ override fun recordDeserializationError (label : String , value : String ) {
140+ AdsClient .deserializationError[label].set(value)
141+ }
142+
143+ override fun recordHttpCacheOutcome (label : String , value : String ) {
144+ AdsClient .httpCacheOutcome[label].set(value)
145+ }
146+ }
147+ ```
68148
69149---
70150
@@ -400,21 +480,40 @@ If the effective TTL resolves to 0 seconds, the response is not cached.
400480
401481#### Example Client Configuration
402482
403- ``` rust
404- // Swift / Kotlin pseudocode
483+ ``` swift
484+ // Swift example
405485let cache = MozAdsCacheConfig (
406486 dbPath : " /tmp/ads_cache.sqlite"
407487 defaultCacheTtlSeconds : 600 , // 10 min
408488 maxSizeMib : 20 // 20 MiB
409489)
410490
491+ let telemetry = AdsClientTelemetry ()
411492let clientCfg = MozAdsClientConfig (
412493 environment : .prod ,
413- cacheConfig: cache
494+ cacheConfig : cache,
495+ telemetry : telemetry
496+ )
497+
498+ let client = MozAdsClient (clientConfig : clientCfg)
499+ ```
500+
501+ ``` kotlin
502+ // Kotlin example
503+ val cache = MozAdsCacheConfig (
504+ dbPath = " /tmp/ads_cache.sqlite"
505+ defaultCacheTtlSeconds = 600L , // 10 min
506+ maxSizeMib = 20L // 20 MiB
414507)
415508
416- let client = MozAdsClient . new (clientConfig: clientCfg)
509+ val telemetry = AdsClientTelemetry ()
510+ val clientCfg = MozAdsClientConfig (
511+ environment = MozAdsEnvironment .PROD ,
512+ cacheConfig = cache,
513+ telemetry = telemetry
514+ )
417515
516+ val client = MozAdsClient (clientCfg)
418517```
419518
420519Where ` db_path ` represents the location of the SQLite file. This must be a file that the client has permission to write to.
0 commit comments