Configuration Reference

`config.yaml` structure

The central configuration file maps services and endpoints to the list of functions that should be tracked. It lives at src/access_py_telemetry/config.yaml.

<service>:
  <endpoint>:
    - ClassName.method_name
    - standalone_function

Fields

Level	Key	Description
Top-level	`<service>`	The name of the client package (e.g. `intake`, `payu`). Typically corresponds to a Django app in the tracking service.
Second-level	`<endpoint>`	The API view path fragment (e.g. `catalog`, `run`). Combined with `<service>` to form the full URL path.
Values	function names	Bare function names or `ClassName.method_name` strings as they appear in parsed user code.

Endpoint naming

The service name used in code (in TelemetryRegister and decorator arguments) is formed by joining the service and endpoint with an underscore:

intake/catalog    →    intake_catalog
payu/run          →    payu_run
mypackage/submit  →    mypackage_submit

Example

intake:
  catalog:
    - esm_datastore.search
    - DfFileCatalog.search
    - DfFileCatalog.__getitem__
  datastore:
    - open_esm_datastore
payu:
  run:
    - Experiment.run
  restart:
    - Experiment.restart

This defines four service names: intake_catalog, intake_datastore, payu_run, payu_restart.

Production vs staging

The ProductionToggle singleton controls which server URL is used:

from access_py_telemetry.api import ProductionToggle

toggle = ProductionToggle()
toggle.production = False  # switch to staging server

Mode	URL
Production (default)	`https://reporting.access-nri-store.cloud.edu.au/api/`
Staging	`https://reporting-dev.access-nri-store.cloud.edu.au/api/`

Session identifiers

Each telemetry record includes a session_id — a SHA-256 hash of a UUID generated at interpreter startup, stable for the lifetime of that Python process:

from access_py_telemetry.api import SessionID

session = SessionID()
print(session)  # e.g. "83006a25092df6bae313f1e4b6be93f8..."

Session IDs change on every interpreter restart and cannot be used to correlate sessions across time.

If you are tracking a CLI tool rather than an interactive session, you may want to remove session_id from the record:

from access_py_telemetry.api import ApiHandler

ApiHandler().remove_fields("myservice_run", ["session_id"])

Checking the registry

To inspect which functions are currently registered for a service:

from access_py_telemetry.registry import TelemetryRegister

registry = TelemetryRegister("intake_catalog")
print(registry)
# ["esm_datastore.search", "DfFileCatalog.search", "DfFileCatalog.__getitem__"]