refactor: improve OpenTelemetry configuration

[evansims]

Description

This change fixes some inconsistencies in how the Python SDK handles the configuration API for its OpenTelemetry support. These changes should improve the developer experience and general usage of the feature.

1. We can now permit a dict-style configuration to be provided, similar to how we support JSON-style approaches in some of the other SDKs.

Current behavior expects classes to be supplied:

from openfga_sdk.telemetry.configuration import (
    TelemetryConfiguration,
    TelemetryMetricConfiguration,
    TelemetryMetricsConfiguration,
)
from openfga_sdk import ClientConfiguration, OpenFgaClient

configuration = ClientConfiguration(
    telemetry=TelemetryConfiguration(
        metrics=TelemetryMetricsConfiguration(
            histogram_request_duration=TelemetryMetricConfiguration(
                attr_fga_client_request_method=True,
                attr_http_response_status_code=True,
            ),
        ),
    ),
    # ...
)

fga = OpenFgaClient(configuration)

After this change, a dict configuration can be provided instead:

from openfga_sdk import ClientConfiguration, OpenFgaClient

configuration = ClientConfiguration(
    telemetry={
        "metrics": {
            "fga-client.credentials.request": {
                "fga-client.request.method": True,
                "http.response.status_code": True,
            },
        },
    },
    # ...
)

fga = OpenFgaClient(configuration)

2. The naming convention of metrics has been updated to more closely match the actual naming used in the counters and histograms created by the SDK rather than aliases. For example, fga_client_credentials_request instead of histogram_request_duration for the fga-client.credentials.request histogram.

counter_client_credentials -> fga_client_credentials_request
histogram_request_duration -> fga_client_request_duration
histogram_query_duration -> fga_client_query_duration

This makes the configuration more self-expressive and offers a better experience, particularly for the dict style configuration.

3. This removes the attr_ prefix from attribute names on TelemetryMetricConfiguration, which makes for a cleaner-looking API in real-world usage.

attr_fga_client_request_client_id -> fga_client_request_client_id

4. By adding an is_enabled helper method to the TelemetryMetricConfiguration class, we will reduce the number of instances of redundant code that check whether a particular metric should be used when metrics are being written.

metric = TelemetryMetricConfiguration()

metric.is_enabled() # False, as nothing is enabled.

metric.fga_client_request_method = True

metric.is_enabled() # True, as `fga_client_request_method` is enabled.

5. Adds is_valid helper method. This will verify the configuration is valid and (optionally) raise an exception if it is not. is_enabled leverages this without raising the exception to ensure the configuration is fully ready for use.

metric = TelemetryMetricConfiguration(
    attr_fga_client_request_method=True,
    attr_http_response_status_code=True,
)

metric.is_valid(fatal: True) # Raises an exception if there is a misconfiguration of some kind.

6. Right now, the configuration's default state is established at initialization time. While this avoids having to have a separate default state scaffolding, it means that unless each attribute is expressly assigned a boolean during initialization, it will be assigned its SDK-supplied default state, which is not ideal.

This means if an application sets:

config = TelemetryMetricConfiguration(
    attr_fga_client_request_method=True,
    attr_http_response_status_code=True,
),

Internally, config will represent this state:

attr_fga_client_request_method=True,
attr_http_response_status_code=True,

# Still inherits the default states of these
attr_fga_client_request_client_id=True,
attr_fga_client_request_model_id=True,
attr_fga_client_request_store_id=True,
attr_fga_client_response_model_id=True,
attr_fga_client_user=False,
attr_http_client_request_duration=False,
attr_http_host=True,
attr_http_request_method=True,
attr_http_request_resend_count=True,
attr_http_server_request_duration=False,
attr_url_scheme=True,
attr_url_full=True,
attr_user_agent_original=True,

These changes update the configuration to default to False, so in the case of:

config = TelemetryMetricConfiguration(
    fga_client_request_method=True,
    http_response_status_code=True,
),

It's state will be:

attr_fga_client_request_method=True,
attr_http_response_status_code=True,

# Still inherits the default states of these
attr_fga_client_request_client_id=False,
attr_fga_client_request_model_id=False,
attr_fga_client_request_store_id=False,
attr_fga_client_response_model_id=False,
attr_fga_client_user=False,
attr_http_client_request_duration=False,
attr_http_host=False,
attr_http_request_method=False,
attr_http_request_resend_count=False,
attr_http_server_request_duration=False,
attr_url_scheme=False,
attr_url_full=False,
attr_user_agent_original=False,

References

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 74.90775% with 136 lines in your changes missing coverage. Please review.

Project coverage is 69.15%. Comparing base (4eb7bbe) to head (5afb454).
Report is 113 commits behind head on main.

Files with missing lines	Patch %	Lines
openfga_sdk/telemetry/configuration.py	69.60%	100 Missing ⚠️
openfga_sdk/telemetry/attributes.py	78.48%	17 Missing ⚠️
openfga_sdk/configuration.py	50.00%	12 Missing ⚠️
openfga_sdk/telemetry/histograms.py	83.33%	2 Missing ⚠️
openfga_sdk/api/open_fga_api.py	94.11%	1 Missing ⚠️
openfga_sdk/api_client.py	88.88%	1 Missing ⚠️
openfga_sdk/sync/api_client.py	87.50%	1 Missing ⚠️
openfga_sdk/telemetry/counters.py	90.90%	1 Missing ⚠️
openfga_sdk/telemetry/metrics.py	95.83%	1 Missing ⚠️

❌ Your project status has failed because the head coverage (69.15%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #127      +/-   ##
==========================================
+ Coverage   69.13%   69.15%   +0.02%     
==========================================
  Files         121      122       +1     
  Lines        9992     9746     -246     
==========================================
- Hits         6908     6740     -168     
+ Misses       3084     3006      -78     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.