Skip to main content

Semantic Layer Sync

If you have centrally defined metrics, Statsig offers the ability to sync its data sources and metrics as part of your data version management workflow. Using Statsig's Console API you can automatically sync changes you make to the matching definitions on Statsig, and you can optionally make the metrics read-only in the Statsig console.

We have a demonstration GitHub repository that utilizes a script executed by a GitHub Action. This setup automatically synchronizes changes to .yml files located in the /metrics or /metric_sources directories in the repo. This means that whenever you create or update these files, the script either updates existing metrics or metric sources in Statsig or creates new ones accordingly.

To use this example template, follow these steps:

  1. Fork this repository to get started.
  2. In your forked repository, add your Statsig Console API Key to GitHub Secrets.
  3. Tailor the metric definitions to align with your data needs.
  4. Verify the automation by modifying relevant files and observing the triggered GitHub Action.

Detailed Guide​

Forking the Repository​

  1. Fork this repository to create a copy in your GitHub account. Untitled

Adding the Statsig Console API Key​

  1. Navigate to Settings > Secrets and variables > Actions in your repository settings. Create a new secret named STATSIG_API_KEY with your Statsig Console API key as its value. This key facilitates authentication with the Statsig Console API for the synchronization process. Untitled

Customizing Metric Definitions​

  1. Metric definitions reside within the ./metrics directory, and metric source definitions are found in the ./metric_sources/ directory. To customize:

    • Utilize the Statsig Console API to fetch an existing metric_source or metric using GET requests for metric sources and metrics.
    • Remove the provided example metrics and metric sources, and replace them with your definitions in ./metric_sources/*.yml and ./metrics/*.yml.

Note: For enhanced readability, we modified metric.warehouseNative[] to metric.metricDefinition[] in our examples. You can see this change here. Feel free to adjust the translations or revert to using metric.warehouseNative[] in your definitions.

Verifying Automation​

  1. To test, edit a metric or metric source description in your repository. This action should trigger the GitHub Action, visible under the Actions tab. The process will then either create or update your metrics and metric sources in Statsig based on the repository's semantic definitions.
Untitled Untitled Untitled

This example serves as a basic template. We encourage testing and further development to meet production standards. Please share any feedback or improvements you've made to this workflow with us in Slack or on email. Thank you for any contributions!