Skip to content

Commit

Permalink
update telemetry docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jimmyjames
jimmyjames committed Sep 23, 2024
1 parent c4be414 commit 58438ec
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 19 deletions.
97 changes: 81 additions & 16 deletions docs/opentelemetry.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,90 @@ In cases when metrics events are sent, they will not be viewable outside of infr

### 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 process the request |
|` fga-client.credentials.request`| Counter | The total number of times a new token was requested when using ClientCredentials|
| Metric Name | Type | Enabled by default | Description |
|---------------------------------|-----------|--------------------|---------------------------------------------------------------------------------|
| `fga-client.request.duration` | Histogram | Yes | The total request time for FGA requests |
| `fga-client.query.duration` | Histogram | Yes | The amount of time the FGA server took to process the request |
|` fga-client.credentials.request`| Counter | Yes | 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 |
| `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 users |
| `http.status_code ` | `int` | The status code of the response |
| `http.method` | `string` | The HTTP method for the request |
| `http.host` | `string` | Host identifier of the origin the request was sent to |
| Attribute Name | Type | Enabled by default | Description |
|--------------------------------|-----------|--------------------|-------------------------------------------------------------------------------------|
| `fga-client.response.model_id` | `string` | Yes | The authorization model ID that the FGA server used |
| `fga-client.request.method` | `string` | Yes | The FGA method/action that was performed |
| `fga-client.request.store_id` | `string` | Yes | The store ID that was sent as part of the request |
| `fga-client.request.model_id` | `string` | Yes | The authorization model ID that was sent as part of the request, if any |
| `fga-client.request.client_id` | `string` | Yes | The client ID associated with the request, if any |
| `fga-client.user` | `string` | No | The user that is associated with the action of the request for check and list users |
| `http.status_code ` | `int` | Yes | The status code of the response |
| `http.request.method` | `string` | No | The HTTP method for the request |
| `http.host` | `string` | Yes | Host identifier of the origin the request was sent to |
| `user_agent.original` | `string` | Yes | The user agent used in the query |
| `url.full` | `string` | No | The full URL of the request |
| `url.scheme` | `string` | No | HTTP Scheme of the request (http/https) |
| `http.request.resend_count` | `int` | Yes | The number of retries attempted |
| `http.client.request.duration` | `int` | No | Time taken by the FGA server to process and evaluate the request, in milliseconds |
| `http.server.request.duration` | `int` | No | The number of retries attempted |

## Default attributes

Not all attributes are enabled by default.

Some attributes, like `fga-client.user` have been disabled by default due to their high cardinality, which may result for very high costs when using some SaaS metric collectors. If you expect to have a high cardinality for a specific attribute, you can disable it by updating the telemetry configuration accordingly.

If your configuration does not specify a given metric, the default attributes for that metric will be used.


```javascript
// define desired telemetry options
const telemetryConfig = {
metrics: {
counterCredentialsRequest: {
attributes: new Set([
TelemetryAttribute.UrlScheme,
TelemetryAttribute.UserAgentOriginal,
TelemetryAttribute.HttpRequestMethod,
TelemetryAttribute.FgaClientRequestClientId,
TelemetryAttribute.FgaClientRequestStoreId,
TelemetryAttribute.FgaClientRequestModelId,
TelemetryAttribute.HttpRequestResendCount,
])
},
histogramRequestDuration: {
attributes: new Set([
TelemetryAttribute.HttpResponseStatusCode,
TelemetryAttribute.UserAgentOriginal,
TelemetryAttribute.FgaClientRequestMethod,
TelemetryAttribute.FgaClientRequestClientId,
TelemetryAttribute.FgaClientRequestStoreId,
TelemetryAttribute.FgaClientRequestModelId,
TelemetryAttribute.HttpRequestResendCount,
])
},
histogramQueryDuration: {
attributes: new Set([
TelemetryAttribute.HttpResponseStatusCode,
TelemetryAttribute.UserAgentOriginal,
TelemetryAttribute.FgaClientRequestMethod,
TelemetryAttribute.FgaClientRequestClientId,
TelemetryAttribute.FgaClientRequestStoreId,
TelemetryAttribute.FgaClientRequestModelId,
TelemetryAttribute.HttpRequestResendCount,
])
}
}
};

const fgaClient = new OpenFgaClient({
apiUrl: process.env.FGA_API_URL,
storeId: process.env.FGA_STORE_ID,
authorizationModelId: process.env.FGA_MODEL_ID,
credentials,
telemetry: telemetryConfig,
});

```

## Example

Expand Down
5 changes: 2 additions & 3 deletions telemetry/attributes.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,11 @@ export enum TelemetryAttribute {
FgaClientRequestStoreId = "fga-client.request.store_id",
FgaClientResponseModelId = "fga-client.response.model_id",
FgaClientUser = "fga-client.user",
// remove this attribute, keep as metric
HttpClientRequestDuration = "http.client.request.duration",
HttpHost = "http.host",
HttpRequestMethod = "http.request.method",
HttpRequestResendCount = "http.request.resend_count",
HttpResponseStatusCode = "http.response.status_code",
// remove this attribute, keep as metric
HttpServerRequestDuration = "http.server.request.duration",
UrlScheme = "url.scheme",
UrlFull = "url.full",
Expand All @@ -26,7 +24,8 @@ export class TelemetryAttributes {
filter?: Set<TelemetryAttribute>
): Record<string, string | number> {
attributes = attributes || {};
filter = filter || new Set();
// ensure we are always using a set
filter = new Set(filter) || new Set();
const result: Record<string, string | number> = {};

for (const key in attributes) {
Expand Down

0 comments on commit 58438ec

Please sign in to comment.