Skip to main content

Configure SDK Client Telemetry

The OpenFGA SDK Client supports telemetry data collection using OpenTelemetry.

Enabling Telemetry

  1. Install the OpenFGA SDK Client
  2. Setup OpenTelemetry
  3. Install the OpenTelemetry SDK dependencies for your application
  4. Instantiate the OpenTelemetry SDK in your application

Once you have completed these steps, the OpenFGA SDK Client will automatically collect telemetry data using your application's OpenTelemetry configuration.

Customizing Telemetry

The OpenFGA SDK Client will automatically use a default configuration for telemetry collection. You can provide your own configuration to include additional metrics or to exclude metrics that are not relevant to your application.

import 'dotenv/config';
import { OpenFgaClient, TelemetryAttribute, TelemetryConfiguration, TelemetryMetric } from '@openfga/sdk';

const telemetryConfig = {
metrics: {
[TelemetryMetric.CounterCredentialsRequest]: {
attributes: new Set([
TelemetryAttribute.UrlScheme,
TelemetryAttribute.UserAgentOriginal,
TelemetryAttribute.HttpRequestMethod,
TelemetryAttribute.FgaClientRequestClientId,
TelemetryAttribute.FgaClientRequestStoreId,
TelemetryAttribute.FgaClientRequestModelId,
TelemetryAttribute.HttpRequestResendCount,
]),
},
[TelemetryMetric.HistogramRequestDuration]: {
attributes: new Set([
TelemetryAttribute.HttpResponseStatusCode,
TelemetryAttribute.UserAgentOriginal,
TelemetryAttribute.FgaClientRequestMethod,
TelemetryAttribute.FgaClientRequestClientId,
TelemetryAttribute.FgaClientRequestStoreId,
TelemetryAttribute.FgaClientRequestModelId,
TelemetryAttribute.HttpRequestResendCount,
]),
},
[TelemetryMetric.HistogramQueryDuration]: {
attributes: new Set([
TelemetryAttribute.HttpResponseStatusCode,
TelemetryAttribute.UserAgentOriginal,
TelemetryAttribute.FgaClientRequestMethod,
TelemetryAttribute.FgaClientRequestClientId,
TelemetryAttribute.FgaClientRequestStoreId,
TelemetryAttribute.FgaClientRequestModelId,
TelemetryAttribute.HttpRequestResendCount,
]),
},
},
};

const fgaClient = new OpenFgaClient({
telemetry: telemetryConfig,
// ...
});

Examples

We provide example applications for using telemetry with the OpenFGA SDK Client.

Supported Metrics

The OpenFGA SDK Client can collect the following metrics:

Metric NameTypeEnabled by DefaultDescription
fga-client.request.durationHistogramYesTotal request time for FGA requests, in milliseconds
fga-client.query.durationHistogramYesTime taken by the FGA server to process and evaluate the request, in milliseconds
fga-client.credentials.requestCounterYesTotal number of new token requests initiated using the Client Credentials flow

Supported Attributes

The OpenFGA SDK Client can collect the following attributes:

Attribute NameTypeEnabled by DefaultDescription
fga-client.request.client_idstringYesClient ID associated with the request, if any
fga-client.request.methodstringYesFGA method/action that was performed (e.g., Check, ListObjects) in TitleCase
fga-client.request.model_idstringYesAuthorization model ID that was sent as part of the request, if any
fga-client.request.store_idstringYesStore ID that was sent as part of the request
fga-client.response.model_idstringYesAuthorization model ID that the FGA server used
fga-client.userstringNoUser associated with the action of the request for check and list users
http.client.request.durationintNoDuration for the SDK to complete the request, in milliseconds
http.hoststringYesHost identifier of the origin the request was sent to
http.request.methodstringYesHTTP method for the request
http.request.resend_countintYesNumber of retries attempted, if any
http.response.status_codeintYesStatus code of the response (e.g., 200 for success)
http.server.request.durationintNoTime taken by the FGA server to process and evaluate the request, in milliseconds
url.schemestringYesHTTP scheme of the request (http/https)
url.fullstringYesFull URL of the request
user_agent.originalstringYesUser Agent used in the query