Skip to content

Commit 7083176

Browse files
evansimsevansims
committed
docs: OpenTelemetry improvements updates
1 parent 9e36918 commit 7083176

4 files changed

Lines changed: 189 additions & 27 deletions

File tree

‎.openapi-generator/FILES‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,7 @@ openfga_sdk/sync/oauth2.py
225225
openfga_sdk/sync/rest.py
226226
openfga_sdk/telemetry/__init__.py
227227
openfga_sdk/telemetry/attributes.py
228+
openfga_sdk/telemetry/configuration.py
228229
openfga_sdk/telemetry/counters.py
229230
openfga_sdk/telemetry/histograms.py
230231
openfga_sdk/telemetry/metrics.py
@@ -247,4 +248,10 @@ test/sync/client/__init__.py
247248
test/sync/client/client_test.py
248249
test/sync/oauth2_test.py
249250
test/sync/open_fga_api_test.py
251+
test/telemetry/attributes_test.py
252+
test/telemetry/configuration_test.py
253+
test/telemetry/counters_test.py
254+
test/telemetry/histograms_test.py
255+
test/telemetry/metrics_test.py
256+
test/telemetry/telemetry_test.py
250257
test/test_open_fga_api.py

‎VERSION.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
0.6.1
1+
0.7.1

‎docs/opentelemetry.md‎

Lines changed: 112 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,121 @@
11
# OpenTelemetry
22

3-
This SDK produces [metrics](https://opentelemetry.io/docs/concepts/signals/metrics/) using [OpenTelemetry](https://opentelemetry.io/) that allow you to view data such as request timings. These metrics also include attributes for the model and store ID, as well as the API called to allow you to build reporting.
3+
- [Overview](#overview)
4+
- [Metrics](#metrics)
5+
- [Supported Metrics](#supported-metrics)
6+
- [Supported Attributes](#supported-attributes)
7+
- [Customizing Reporting](#customizing-reporting)
8+
- [Usage](#usage)
9+
- [Installation](#1-install-dependencies)
10+
- [Configure OpenTelemetry](#2-configure-opentelemetry)
11+
- [Configure OpenFGA](#3-configure-openfga)
12+
- [Example Integration](#example-integration)
413

5-
When an OpenTelemetry SDK instance is configured, the metrics will be exported and sent to the collector configured as part of your applications configuration. If you are not using OpenTelemetry, the metric functionality is a no-op and the events are never sent.
14+
## Overview
615

7-
In cases when metrics events are sent, they will not be viewable outside of infrastructure configured in your application, and are never available to the OpenFGA team or contributors.
16+
This SDK supports [OpenTelemetry](https://opentelemetry.io/) to export [metrics](https://opentelemetry.io/docs/concepts/signals/metrics/) that provide insights into your application's performance, such as request timings. These metrics include attributes like model and store IDs, and the API called, which you can use to build detailed reports and dashboards.
17+
18+
If you configure the OpenTelemetry SDK, these metrics will be exported and sent to a collector as specified in your application's configuration. If OpenTelemetry is not configured, metrics functionality is disabled, and no events are sent.
819

920
## Metrics
1021

1122
### Supported Metrics
1223

13-
| Metric Name | Type | Description |
14-
| --------------------------------- | --------- | -------------------------------------------------------------------------------- |
15-
| `fga-client.request.duration` | Histogram | The total request time for FGA requests |
16-
| `fga-client.query.duration` | Histogram | The amount of time the FGA server took to process the request |
17-
| ` fga-client.credentials.request` | Counter | The total number of times a new token was requested when using ClientCredentials |
18-
19-
### Supported attributes
20-
21-
| Attribute Name | Type | Description |
22-
| ------------------------------ | -------- | ----------------------------------------------------------------------------------- |
23-
| `fga-client.response.model_id` | `string` | The authorization model ID that the FGA server used |
24-
| `fga-client.request.method` | `string` | The FGA method/action that was performed |
25-
| `fga-client.request.store_id` | `string` | The store ID that was sent as part of the request |
26-
| `fga-client.request.model_id` | `string` | The authorization model ID that was sent as part of the request, if any |
27-
| `fga-client.request.client_id` | `string` | The client ID associated with the request, if any |
28-
| `fga-client.user` | `string` | The user that is associated with the action of the request for check and list users |
29-
| `http.status_code ` | `int` | The status code of the response |
30-
| `http.method` | `string` | The HTTP method for the request |
31-
| `http.host` | `string` | Host identifier of the origin the request was sent to |
32-
33-
## Example
34-
35-
There is an [example project](https://github.com/openfga/python-sdk/blob/main/example/opentelemetry) that provides some guidance on how to configure OpenTelemetry available in the examples directory.
24+
| Metric Name | Type | Enabled by Default | Description |
25+
| -------------------------------- | --------- | ------------------ | --------------------------------------------------------------------------------- |
26+
| `fga-client.request.duration` | Histogram | Yes | Total request time for FGA requests, in milliseconds |
27+
| `fga-client.query.duration` | Histogram | Yes | Time taken by the FGA server to process and evaluate the request, in milliseconds |
28+
| `fga-client.credentials.request` | Counter | Yes | Total number of new token requests initiated using the Client Credentials flow |
29+
30+
### Supported Attributes
31+
32+
| Attribute Name | Type | Enabled by Default | Description |
33+
| ------------------------------ | ------ | ------------------ | --------------------------------------------------------------------------------- |
34+
| `fga-client.request.client_id` | string | Yes | Client ID associated with the request, if any |
35+
| `fga-client.request.method` | string | Yes | FGA method/action that was performed (e.g., Check, ListObjects) in TitleCase |
36+
| `fga-client.request.model_id` | string | Yes | Authorization model ID that was sent as part of the request, if any |
37+
| `fga-client.request.store_id` | string | Yes | Store ID that was sent as part of the request |
38+
| `fga-client.response.model_id` | string | Yes | Authorization model ID that the FGA server used |
39+
| `fga-client.user` | string | No | User associated with the action of the request for check and list users |
40+
| `http.client.request.duration` | int | No | Duration for the SDK to complete the request, in milliseconds |
41+
| `http.host` | string | Yes | Host identifier of the origin the request was sent to |
42+
| `http.request.method` | string | Yes | HTTP method for the request |
43+
| `http.request.resend_count` | int | Yes | Number of retries attempted, if any |
44+
| `http.response.status_code` | int | Yes | Status code of the response (e.g., `200` for success) |
45+
| `http.server.request.duration` | int | Yes | Time taken by the FGA server to process and evaluate the request, in milliseconds |
46+
| `url.scheme` | string | Yes | HTTP scheme of the request (`http`/`https`) |
47+
| `url.full` | string | Yes | Full URL of the request |
48+
| `user_agent.original` | string | Yes | User Agent used in the query |
49+
50+
## Customizing Reporting
51+
52+
To control which metrics and attributes are reported by the SDK, you can provide your own `TelemetryConfiguration` instance during initialization, as shown in the example above. The `TelemetryConfiguration` class allows you to configure the metrics and attributes that are reported by the SDK, as outlined in [the tables above](#metrics).
53+
54+
## Usage
55+
56+
### 1. Install Dependencies
57+
58+
Install the OpenFGA SDK and OpenTelemetry SDK in your application using `pip`:
59+
60+
```sh
61+
pip install openfga opentelemetry-sdk
62+
```
63+
64+
You must also install an OpenTelemetry exporter; for example, the OTLP gRPC exporter:
65+
66+
```sh
67+
pip install opentelemetry-exporter-otlp-proto-grpc
68+
```
69+
70+
### 2. Configure OpenTelemetry
71+
72+
Configure your application to use OpenTelemetry, and set up the metrics provider to export metrics using an exporter:
73+
74+
```python
75+
from opentelemetry import metrics
76+
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
77+
from opentelemetry.sdk.metrics import MeterProvider
78+
79+
# Configure OpenTelemetry
80+
metrics.set_meter_provider(
81+
MeterProvider(
82+
resource=Resource(attributes={SERVICE_NAME: "openfga-example"}),
83+
metric_readers=[PeriodicExportingMetricReader(OTLPMetricExporter())],
84+
)
85+
)
86+
```
87+
88+
### 3. Configure OpenFGA
89+
90+
Configure the OpenFGA client, and (optionally) customize what metrics and attributes are reported:
91+
92+
```python
93+
from openfga_sdk.telemetry.configuration import (
94+
TelemetryConfiguration,
95+
TelemetryMetricConfiguration,
96+
TelemetryMetricsConfiguration,
97+
)
98+
from openfga_sdk import ClientConfiguration, OpenFgaClient
99+
100+
configuration = ClientConfiguration(
101+
api_url=os.getenv("FGA_API_URL"),
102+
store_id=os.getenv("FGA_STORE_ID"),
103+
authorization_model_id=os.getenv("FGA_AUTHORIZATION_MODEL_ID"),
104+
105+
# If you are comfortable with the default configuration outlined in the tables above, you can omit providing your own TelemetryConfiguration object.
106+
telemetry=TelemetryConfiguration(
107+
metrics=TelemetryMetricsConfiguration(
108+
histogram_request_duration=TelemetryMetricConfiguration(
109+
attr_fga_client_request_method=True,
110+
attr_http_response_status_code=True,
111+
),
112+
),
113+
),
114+
)
115+
116+
fga = OpenFgaClient(configuration)
117+
```
118+
119+
## Example Integration
120+
121+
An [example integration](../example/opentelemetry) is provided that also demonstrates how to configure an application with OpenFGA and OpenTelemetry. Please refer to [the README](../example/opentelemetry/README.md) for more information.

‎example/opentelemetry/main.py‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@
1515
)
1616
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
1717

18+
from openfga_sdk.telemetry.configuration import (
19+
TelemetryConfiguration,
20+
TelemetryMetricConfiguration,
21+
TelemetryMetricsConfiguration,
22+
)
23+
1824
# For usage convenience of this example, we will import the OpenFGA SDK from the parent directory.
1925
sdk_path = os.path.realpath(os.path.join(os.path.abspath(__file__), "..", "..", ".."))
2026
sys.path.insert(0, sdk_path)
@@ -42,6 +48,7 @@ def __init__(
4248
client: OpenFgaClient = None,
4349
credentials: Credentials = None,
4450
configuration: ClientConfiguration = None,
51+
telemetry: TelemetryConfiguration = None,
4552
):
4653
"""
4754
Initialize the example with the provided client, credentials, and configuration.
@@ -50,6 +57,7 @@ def __init__(
5057
self._client = client
5158
self._credentials = credentials
5259
self._configuration = configuration
60+
self._telemetry = telemetry
5361

5462
async def fga_client(self, env: dict[str, str] = {}) -> OpenFgaClient:
5563
"""
@@ -78,6 +86,67 @@ async def fga_client(self, env: dict[str, str] = {}) -> OpenFgaClient:
7886
credentials=self._credentials,
7987
)
8088

89+
if not self._telemetry:
90+
# Configure the telemetry metrics to be collected.
91+
# Note: the following represents the default configuration values, so unless you want to change them, you can omit this step.
92+
self._telemetry = TelemetryConfiguration(
93+
metrics=TelemetryMetricsConfiguration(
94+
counter_credentials_request=TelemetryMetricConfiguration(
95+
attr_fga_client_request_client_id=True,
96+
attr_fga_client_request_method=True,
97+
attr_fga_client_request_model_id=True,
98+
attr_fga_client_request_store_id=True,
99+
attr_fga_client_response_model_id=True,
100+
attr_fga_client_user=False,
101+
attr_http_client_request_duration=False,
102+
attr_http_host=True,
103+
attr_http_request_method=True,
104+
attr_http_request_resend_count=True,
105+
attr_http_response_status_code=True,
106+
attr_http_server_request_duration=False,
107+
attr_http_url_scheme=True,
108+
attr_http_url_full=True,
109+
attr_user_agent_original=True,
110+
),
111+
histogram_request_duration=TelemetryMetricConfiguration(
112+
attr_fga_client_request_client_id=True,
113+
attr_fga_client_request_method=True,
114+
attr_fga_client_request_model_id=True,
115+
attr_fga_client_request_store_id=True,
116+
attr_fga_client_response_model_id=True,
117+
attr_fga_client_user=False,
118+
attr_http_client_request_duration=False,
119+
attr_http_host=True,
120+
attr_http_request_method=True,
121+
attr_http_request_resend_count=True,
122+
attr_http_response_status_code=True,
123+
attr_http_server_request_duration=False,
124+
attr_http_url_scheme=True,
125+
attr_http_url_full=True,
126+
attr_user_agent_original=True,
127+
),
128+
histogram_query_duration=TelemetryMetricConfiguration(
129+
attr_fga_client_request_client_id=True,
130+
attr_fga_client_request_method=True,
131+
attr_fga_client_request_model_id=True,
132+
attr_fga_client_request_store_id=True,
133+
attr_fga_client_response_model_id=True,
134+
attr_fga_client_user=False,
135+
attr_http_client_request_duration=False,
136+
attr_http_host=True,
137+
attr_http_request_method=True,
138+
attr_http_request_resend_count=True,
139+
attr_http_response_status_code=True,
140+
attr_http_server_request_duration=False,
141+
attr_http_url_scheme=True,
142+
attr_http_url_full=True,
143+
attr_user_agent_original=True,
144+
),
145+
),
146+
)
147+
148+
self._configuration.telemetry = self._telemetry
149+
81150
if not self._client:
82151
return OpenFgaClient(self._configuration)
83152

0 commit comments

Comments
 (0)