TabPFN Common Utilities

Common errors

• ModuleNotFoundError: No module named 'posthog'

  cause The 'posthog' library, a core dependency for telemetry, is not installed.
  fix Install the required dependency: `pip install posthog` or `pip install tabpfn-common-utils` which should pull it in.

• Telemetry events are not appearing in PostHog dashboard.

  cause The `TelemetryClient` might not be initialized with a valid `POSTHOG_API_KEY`, or there could be network issues preventing data transmission.
  fix Verify that the `POSTHOG_API_KEY` environment variable is correctly set and is a valid key for your PostHog instance. Alternatively, ensure you pass a valid `api_key` argument during `TelemetryClient` initialization. Check network connectivity and PostHog server status.

• AttributeError: 'NoneType' object has no attribute 'capture'

  cause This usually indicates that the `TelemetryClient` object was not successfully instantiated, or was perhaps inadvertently assigned `None`.
  fix Double-check the `TelemetryClient` initialization. Ensure no exceptions occurred during its creation and that it's being used after a successful instantiation. If using `TabPFNLogger`, ensure it's provided with a valid `telemetry_client` instance.

Warnings

• gotcha Telemetry data is sent to PostHog by default. If you need to disable or control this for privacy or compliance, ensure you configure the `TelemetryClient` appropriately or set environment variables like `TABPFN_DISABLE_TELEMETRY`.
  Fix: Consult the source code or documentation for specific environment variables or constructor arguments to disable or configure telemetry. For instance, setting `POSTHOG_API_KEY` to an empty string might effectively disable it, or checking for an explicit 'disable' flag in future versions.
• gotcha The `TelemetryClient` relies on the `POSTHOG_API_KEY` environment variable or direct `api_key` argument for proper functioning. If not provided or incorrect, telemetry events may not be sent, or the client might fail silently.
  Fix: Ensure `POSTHOG_API_KEY` is set correctly in your environment, or pass the `api_key` explicitly when initializing `TelemetryClient`. Verify network access if events are still not reaching PostHog.
• breaking Older versions (prior to v0.2.14) had an issue with timezone awareness for timestamps. This could lead to incorrect timestamps in telemetry data if not handled carefully.
  Fix: Upgrade to version `0.2.14` or newer to ensure correct timezone handling for telemetry events. If on older versions, ensure all timestamps are explicitly timezone-aware before passing them to the utility functions.

Install

• pip install tabpfn-common-utils Install stable version

Imports

• TelemetryClient

  from tabpfn_common_utils.telemetry.client import TelemetryClient

• TabPFNLogger

  from tabpfn_common_utils.telemetry.logger import TabPFNLogger

• TelemetryEvent

  from tabpfn_common_utils.telemetry.events import TelemetryEvent

Quickstart

This quickstart demonstrates how to initialize the `TelemetryClient` and `TabPFNLogger`. The `TelemetryClient` is configured to use an environment variable for the PostHog API key, falling back to a dummy key for development. It then logs an informational message and captures a custom telemetry event.

import os
from tabpfn_common_utils.telemetry.client import TelemetryClient
from tabpfn_common_utils.telemetry.logger import TabPFNLogger

# Initialize TelemetryClient (API key can be passed directly or via POSTHOG_API_KEY env var)
# For local testing, set POSTHOG_API_KEY in your environment, or pass a dummy string.
# Data won't be sent if API key is invalid or not set in a production context.
telemetry_client = TelemetryClient(
    api_key=os.environ.get('POSTHOG_API_KEY', 'phc_dummy_key_for_dev'),
    project_group="quickstart",
    project_name="example"
)

# Initialize TabPFNLogger
logger = TabPFNLogger(telemetry_client=telemetry_client)

# Log a message
logger.info("Quickstart example executed.")

# Capture a custom event
telemetry_client.capture(
    event_name="quickstart_event",
    properties={
        "data_point_count": 100,
        "model_type": "test_model"
    }
)

print("Telemetry client and logger initialized and events captured (if API key is valid).")