feat: improvements to OpenTelemetry metrics

openfga · Jul 25, 2024 · e6789d6 · e6789d6
1 parent b1e03e5
commit e6789d6
Show file tree

Hide file tree

Showing 13 changed files with 357 additions and 105 deletions.
diff --git a/README.md b/README.md
@@ -46,6 +46,7 @@ This is an autogenerated Java SDK for OpenFGA. It provides a wrapper around the
   - [Retries](#retries)
   - [API Endpoints](#api-endpoints)
   - [Models](#models)
+  - [OpenTelemetry](#models)
 - [Contributing](#contributing)
   - [Issues](#issues)
   - [Pull Requests](#pull-requests)
@@ -1058,7 +1059,10 @@ public class Example {
 
 - [WriteRequestWrites](https://github.com/openfga/java-sdk/blob/main/docs/WriteRequestWrites.md)
 
+### OpenTelemetry
 
+This SDK supports producing metrics that can be consumed as part of an [OpenTelemetry](https://opentelemetry.io/) setup.
+For more information, please see [the documentation](https://github.com/openfga/java-sdk/blob/main/OpenTelemetry.md)
 
 ## Contributing
 

diff --git a/build.gradle b/build.gradle
@@ -65,8 +65,8 @@ dependencies {
     implementation "com.fasterxml.jackson.core:jackson-annotations:$jackson_version"
     implementation "com.fasterxml.jackson.core:jackson-databind:$jackson_version"
     implementation "com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jackson_version"
-    implementation "org.openapitools:jackson-databind-nullable:0.2.6"
-    implementation platform("io.opentelemetry:opentelemetry-bom:1.40.0")
+    implementation "org.openapitools:jackson-databind-nullable:0.2.+"
+    implementation platform("io.opentelemetry:opentelemetry-bom:1.40.+")
     implementation "io.opentelemetry:opentelemetry-api"
 }
 

diff --git a/docs/OpenTelemetry.md b/docs/OpenTelemetry.md
@@ -0,0 +1,44 @@
+# OpenTelemetry
+
+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.
+
+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.
+
+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.
+
+## Metrics
+
+### Supported Metrics
+
+| Metric Name                       | Type      | Description                                                                          |
+| --------------------------------- | --------- | ------------------------------------------------------------------------------------ |
+| `fga-client.request.duration`     | Histogram | The total request time for FGA requests                                              |
+| `fga-client.query.duration`       | Histogram | The amount of time the FGA server took to internally process nd evaluate the request |
+| ` fga-client.credentials.request` | Counter   | The total number of times a new token was requested when using ClientCredentials     |
+
+### Supported attributes
+
+| Attribute Name                 | Type     | Description                                                                                                             |
+| ------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `fga-client.response.model_id` | `string` | The authorization model ID that the FGA server used                                                                     |
+| `fga-client.request.method`    | `string` | The FGA method/action that was performed (e.g. `check`, `listObjects`, ...) in camelCase                                |
+| `fga-client.request.store_id`  | `string` | The store ID that was sent as part of the request                                                                       |
+| `fga-client.request.model_id`  | `string` | The authorization model ID that was sent as part of the request, if any                                                 |
+| `fga-client.request.client_id` | `string` | The client ID associated with the request, if any                                                                       |
+| `fga-client.user`              | `string` | The user that is associated with the action of the request for check and list objects                                   |
+| `fga-client.request.retries`   | `int`    | The number of retries attempted (starting from 1 for the original request). Deprecated, use `http.request.resend_count` |
+| `http.request.resend_count`    | `int`    | The number of retries attempted (starting from 1 for the original request)                                              |
+| `http.status_code`             | `int`    | The status code of the response. Deprecated, use `http.response.status_code`                                            |
+| `http.response.status_code`    | `int`    | The status code of the response                                                                                         |
+| `http.method`                  | `string` | The HTTP method for the request. Deprecated, use `http.request.method`                                                  |
+| `http.request.method`          | `string` | The HTTP method for the request                                                                                         |
+| `http.host`                    | `string` | Host identifier of the origin the request was sent to                                                                   |
+| `url.scheme`                   | `string` | HTTP Scheme of the request (`http`/`https`)                                                                             |
+| `url.full`                     | `string` | Full URL of the request                                                                                                 |
+| `user_agent.original`          | `string` | User Agent used in the query                                                                                            |
+| `http.client.request.duration` | `int`    | The total request time for FGA requests                                                                                 |
+| `http.server.request.duration` | `int`    | The amount of time the FGA server took to internally process nd evaluate the request                                    |
+
+## Example
+
+There is an [example project](https://github.com/openfga/java-sdk/blob/main/example/opentelemetry) that provides some guidance on how to configure OpenTelemetry available in the examples directory.
diff --git a/example/example1/build.gradle b/example/example1/build.gradle
@@ -19,11 +19,11 @@ repositories {
 }
 
 ext {
-    jacksonVersion = "2.16.0"
+    jacksonVersion = "2.17.1"
 }
 
 dependencies {
-    implementation("dev.openfga:openfga-sdk:0.4.+")
+    implementation("dev.openfga:openfga-sdk:0.5.+")
 
     // Serialization
     implementation("com.fasterxml.jackson.core:jackson-core:$jacksonVersion")