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

Tracing​

OpenFGA supports tracing with OpenTelemetry.

If your application uses OpenTelemetry tracing, traces will be propagated to OpenFGA, provided the traces are exported to the same address. This can be useful to help diagnose any suspected performance issues when using OpenFGA.

If your application does not already use tracing, OpenTelemetry offers zero-code instrumentation for several languages. For example, a TypeScript application can be configured with tracing by using one of the OpenTelemetry JavaScript Instrumentation Libraries:

npm install --save @opentelemetry/auto-instrumentations-node

Create an initialization file to configure tracing:

// tracing.ts
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
  // registers all instrumentation packages, you may wish to change this
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

Run the application with the appropriate OTEL environment variables:

OTEL_SERVICE_NAME='YOUR-SERVICE-NAME' ts-node -r ./tracing.ts YOUR-APP.ts

See the OpenTelemetry documentation for additional information to configure your application for tracing.