Skip to main content

Monitoring the SDK

Statsig SDKs provide two main ways of monitoring the SDK's behavior and performance:

  1. Logs: The SDK logs important events and errors to help you understand event-by-event how Statsig is behaving in your application.
  2. Metrics: The SDK emits metrics to help you understand the aggregate performance of the SDK its impact on your application.

Supported SDKs: Most SDKs have some level of logging, but our latest release of structured logging and metrics, is currently only available by the Python SDK.

Logging Levels and Expected Information​

The Statsig SDK uses multiple logging levels to communicate various information types. Here’s what each logging level represents and what kind of details you can expect:

  • Debug: Detailed logs useful for new users onboarding with the SDK and for diagnosing potential issues, such as:
    • Messages when a feature gate does not exist
    • Tracking process flows within the SDK
  • Info: General information about the SDK’s operation, typically relevant to regular usage, such as:
    • Messages regarding SDK initialization, including source and version information
    • Notifications when the configuration store is populated
  • Warning: Logs about unusual events that may impact functionality but are automatically managed and recovered, such as:
    • Messages on non critical errors caught by the SDK
    • Notifications about reconnection attempts to gRPC services
  • Error: Critical logs about issues that severely impact the SDK’s functionality, such as:
    • Messages about initialization failures or timeouts
    • Notifications indicating gRPC fallback, suggesting gRPC is unavailable or incorrect configuration

SDK Metrics​

Some Statsig SDKs provide built-in metrics to help you monitor its performance and impact on your application. The specific implementation may vary by programming language, refer to the documentation for the language-specific SDK interface.

Metric Interface Methods​

The following interface methods are provided by the Statsig SDK to track various metrics:

  • Initialization (init): This method is called on sdk initialization and allows users to initialize their observability client (such as StatsD, OpenTelemetry, etc.), preparing the SDK to send metrics and logs to the chosen observability tool.
  • Shutdown (shutdown): This method is called on sdk shutdown, and allow users to perform any actions to ensure graceful shutdown of the observability client, such as ensuring that any pending metrics or logs are properly handled and sent before the SDK is terminated.
  • Counter: A method that tracks occurrences of specific events.
  • Gauge: A method used to record point-in-time values, such as the number of active connections or other metrics that don’t accumulate over time.
  • Distribution: A method that tracks distributions of numerical data over time, such as latency or response times.
  • Should Enable High Cardinality Tags: This method is called on high cardinality tags and allows users to define if certain high cardinality tags (which can generate large data volumes) should be enabled for detailed tracking. By default, all high cardinality tags are disabled.

List of Metrics​

Below is a list of the primary metrics currently available in the SDK:

Metric NameTypeTagsDescription
statsig.sdk.initializationdistributionsuccess, init_source, init_source_api, store_populatedTracks SDK initialization duration.
statsig.sdk.config_propagation_diffdistributionsource, source_api, lcut*, prev_lcut*Measures the time difference between the last config updated time vs the time that sdk received the config.
statsig.sdk.config_no_updatecountersource, source_apiTracks occurrences of no configuration updates.

Note: Tags marked with * (such as lcut and prev_lcut) are high cardinality tags.

Metric Tags​

High cardinality tags are tags that can generate large data dimensions when enabled. These tags are disabled by default, but can be enabled as through Should Enable High Cardinality Tags method on the observability client interface. High cardinality tags include:

  • lcut: The last configuration update timestamp.
  • prev_lcut: The previous configuration update timestamp.

Metric Tags:

  • source: The source of the configuration update, such as network/bootstrap/datastore.
  • source_api: The API endpoint used to fetch the configuration update.
  • success: Indicates whether the initialization was successful.
  • store_populated: Indicates whether the configuration store was populated.