release(js-sdk): v0.6.0

Makefile

@@ -66,6 +66,7 @@ build-client-js:
 	sed -i -e "s|_this|this|g" ${CLIENTS_OUTPUT_DIR}/fga-js-sdk/*.md
 	rm -rf  ${CLIENTS_OUTPUT_DIR}/fga-js-sdk/*-e
 	make run-in-docker sdk_language=js image=node:${NODE_DOCKER_TAG} command="/bin/sh -c 'npm i --lockfile-version 2 && npm run lint:fix -- --quiet'"
+	make run-in-docker sdk_language=js image=busybox:${BUSYBOX_DOCKER_TAG} command="/bin/sh -c 'patch -p1 api.ts /config/clients/js/patches/add-method-specific-attributes.patch'"
 	make run-in-docker sdk_language=js image=node:${NODE_DOCKER_TAG} command="/bin/sh -c 'npm run lint:fix && npm run build;'"
 
 ### Go

config/clients/js/CHANGELOG.md.mustache

@@ -1,5 +1,10 @@
 # Changelog
 
+## v0.6.0
+
+### [0.6.0](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/compare/v0.5.0...v0.6.0) (2024-06-28)
+- feat: add opentelemetry metrics reporting (#117)
+
 ## v0.5.0
 
 ### [0.5.0](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/compare/v0.4.0...v0.5.0) (2024-06-14)

config/clients/js/config.overrides.json

@@ -2,14 +2,15 @@
   "sdkId": "js",
   "gitRepoId": "js-sdk",
   "packageName": "@openfga/sdk",
-  "packageVersion": "0.5.0",
+  "packageVersion": "0.6.0",
   "packageDescription": "JavaScript and Node.js SDK for OpenFGA",
   "packageDetailedDescription": "This is an autogenerated JavaScript SDK for OpenFGA. It provides a wrapper around the [OpenFGA API definition](https://openfga.dev/api), and includes TS typings.",
   "npmRegistry": "https://registry.npmjs.org/",
   "fossaComplianceNoticeId": "9c7d9da4-2a75-47c9-bfc9-31b301fb764f",
   "useSingleRequestParameter": false,
   "supportsES6": true,
   "modelPropertyNaming": "original",
+  "supportsOpenTelemetry": true,
   "files": {
     ".github/workflows/main.yaml.mustache": {
       "destinationFilename": ".github/workflows/main.yaml",
@@ -118,6 +119,11 @@
       "destinationFilename": "example/example1/package.json",
       "templateType": "SupportingFiles"
     },
-    ".madgerc": {}
+    ".madgerc": {},
+    "telemetry.mustache": {
+      "destinationFilename": "telemetry.ts",
+      "templateType": "SupportingFiles"
+    },
+    "docs/opentelemetry.md": {}
   }
 }

config/clients/js/patches/add-method-specific-attributes.patch

@@ -0,0 +1,118 @@
+diff --git a/api.ts b/api.ts
+index e45e6c2..260e0bc 100644
+--- a/api.ts
++++ b/api.ts
+@@ -759,6 +759,8 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.check(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "check",
++        [attributeNames.requestStoreId]: storeId,
++        [attributeNames.user]: body.tuple_key.user
+       });
+     },
+     /**
+@@ -785,6 +787,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.deleteStore(storeId, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "deleteStore",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -799,6 +802,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.expand(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "expand",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -812,6 +816,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.getStore(storeId, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "getStore",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -826,6 +831,8 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.listObjects(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "listObjects",
++        [attributeNames.requestStoreId]: storeId,
++        [attributeNames.user]: body.user
+       });
+     },
+     /**
+@@ -854,6 +861,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.listUsers(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "listUsers",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -868,6 +876,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.read(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "read",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -882,6 +891,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.readAssertions(storeId, authorizationModelId, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "readAssertions",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -896,6 +906,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.readAuthorizationModel(storeId, id, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "readAuthorizationModel",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -911,6 +922,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.readAuthorizationModels(storeId, pageSize, continuationToken, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "readAuthorizationModels",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -927,6 +939,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.readChanges(storeId, type, pageSize, continuationToken, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "readChanges",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -941,6 +954,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.write(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "write",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -956,6 +970,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.writeAssertions(storeId, authorizationModelId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "writeAssertions",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+     /**
+@@ -970,6 +985,7 @@ export const OpenFgaApiFp = function(configuration: Configuration, credentials:
+       const localVarAxiosArgs = await localVarAxiosParamCreator.writeAuthorizationModel(storeId, body, options);
+       return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+         [attributeNames.requestMethod]: "writeAuthorizationModel",
++        [attributeNames.requestStoreId]: storeId,
+       });
+     },
+   };

config/clients/js/template/.github/dependabot.yaml

@@ -17,4 +17,4 @@ updates:
     groups:
      dependencies:
         patterns:
-          - "*"
+          - "*"

config/clients/js/template/.github/workflows/main.yaml.mustache

@@ -19,7 +19,7 @@ jobs:
         node-version: [14, 16, 18, 20]
 
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           fetch-depth: 0
 
@@ -42,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           fetch-depth: 0
 
@@ -65,7 +65,7 @@ jobs:
         run: npm test
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@125fc84a9a348dbcf27191600683ec096ec9021c # v4.4.1
+        uses: codecov/codecov-action@e28ff129e5465c2c0dcc6f003fc735cb6ae0c673 # v4.5.0
         continue-on-error: true
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -81,7 +81,7 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           fetch-depth: 0
 
@@ -111,7 +111,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
         with:
           fetch-depth: 0
 

config/clients/js/template/api.mustache

@@ -14,6 +14,7 @@ import {
     CallResult,
     PromiseResult
 } from './common';
+import { attributeNames } from "./telemetry";
 import { Configuration } from './configuration';
 import { Credentials } from "./credentials";
 import { assertParamExists } from './validation';

config/clients/js/template/apiInner.mustache

@@ -211,7 +211,9 @@ export const {{classname}}Fp = function(configuration: Configuration, credential
          */
         async {{nickname}}({{#allParams}}{{paramName}}{{^required}}?{{/required}}: {{{dataType}}}, {{/allParams}}options?: any): Promise<(axios?: AxiosInstance) => PromiseResult<{{#returnType}}{{{returnType}}}{{/returnType}}{{^returnType}}void{{/returnType}}>> {
             const localVarAxiosArgs = await localVarAxiosParamCreator.{{nickname}}({{#allParams}}{{paramName}}, {{/allParams}}options);
-            return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials);
+            return createRequestFunction(localVarAxiosArgs, globalAxios, configuration, credentials, {
+                [attributeNames.requestMethod]: "{{nickname}}",
+            });
         },
     {{/operation}}
     }

config/clients/js/template/common.mustache

@@ -1,6 +1,7 @@
 {{>partial_header}}
 
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
+import { metrics } from "@opentelemetry/api";
 
 import { Configuration } from "./configuration";
 import type { Credentials } from "./credentials";
@@ -14,6 +15,17 @@ import {
   FgaError
 } from "./errors";
 import { setNotEnumerableProperty } from "./utils";
+import { buildAttributes } from "./telemetry";
+
+const meter = metrics.getMeter("{{packageName}}", "{{packageVersion}}");
+const durationHist = meter.createHistogram("fga-client.request.duration", {
+  description: "The duration of requests",
+  unit: "milliseconds",
+});
+const queryDurationHist = meter.createHistogram("fga-client.query.duration", {
+  description: "The duration of queries on the FGA server",
+  unit: "milliseconds",
+});
 
 /**
  *
@@ -169,13 +181,15 @@ export async function attemptHttpRequest<B, R>(
 /**
  * creates an axios request function
  */
-export const createRequestFunction = function (axiosArgs: RequestArgs, axiosInstance: AxiosInstance, configuration: Configuration, credentials: Credentials) {
+export const createRequestFunction = function (axiosArgs: RequestArgs, axiosInstance: AxiosInstance, configuration: Configuration, credentials: Credentials, methodAttributes: Record<string, unknown> = {}) {
   configuration.isValid();
 
   const retryParams = axiosArgs.options?.retryParams ? axiosArgs.options?.retryParams : configuration.retryParams;
   const maxRetry:number = retryParams ? retryParams.maxRetry : 0;
   const minWaitInMs:number = retryParams ? retryParams.minWaitInMs : 0;
 
+  const start = Date.now();
+
   return async (axios: AxiosInstance = axiosInstance) : PromiseResult<any> => {
     await setBearerAuthToObject(axiosArgs.options.headers, credentials!);
 
@@ -184,9 +198,23 @@ export const createRequestFunction = function (axiosArgs: RequestArgs, axiosInst
       maxRetry,
       minWaitInMs,
     }, axios);
+    const executionTime = Date.now() - start;
+
     const data = typeof response?.data === "undefined" ? {} : response?.data;
     const result: CallResult<any> = { ...data };
     setNotEnumerableProperty(result, "$response", response);
+
+    const attributes = buildAttributes(response, configuration.credentials, methodAttributes);
+
+    if (response?.headers) {
+      const duration = response.headers["fga-query-duration-ms"];
+      if (duration !== undefined) {
+        queryDurationHist.record(parseInt(duration, 10), attributes);
+      }
+    }
+
+    durationHist.record(executionTime, attributes);
+
     return result;
   };
 };

config/clients/js/template/credentials/credentials.ts.mustache

@@ -5,11 +5,14 @@ import globalAxios, { AxiosInstance } from "axios";
 import { assertParamExists, isWellFormedUriString } from "../validation";
 import { FgaApiAuthenticationError, FgaApiError, FgaError, FgaValidationError } from "../errors";
 import { attemptHttpRequest } from "../common";
+import { buildAttributes } from "../telemetry";
 import { ApiTokenConfig, AuthCredentialsConfig, ClientCredentialsConfig, CredentialsMethod } from "./types";
+import { Counter, metrics } from "@opentelemetry/api";
 
 export class Credentials {
   private accessToken?: string;
   private accessTokenExpiryDate?: Date;
+  private tokenCounter?: Counter;
 
   public static init(configuration: { credentials: AuthCredentialsConfig }): Credentials {
     return new Credentials(configuration.credentials);
@@ -37,7 +40,11 @@ export class Credentials {
         }
       }
       break;
-    case CredentialsMethod.ClientCredentials:
+    case CredentialsMethod.ClientCredentials: {
+      const meter = metrics.getMeter("{{packageName}}", "{{packageVersion}}");
+      this.tokenCounter = meter.createCounter("fga-client.credentials.request");
+      break;
+    }
     case CredentialsMethod.None:
     default:
       break;
@@ -147,6 +154,8 @@ export class Credentials {
         this.accessTokenExpiryDate = new Date(Date.now() + response.data.expires_in * 1000);
       }
 
+    this.tokenCounter?.add(1, buildAttributes(response, this.authConfig));
+
       return this.accessToken;
     } catch (err: unknown) {
       if (err instanceof FgaApiError) {

config/clients/js/template/docs/opentelemetry.md

@@ -0,0 +1,31 @@
+# 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 process 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                                            |
+| `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                               |

config/clients/js/template/package.mustache

@@ -19,6 +19,8 @@
     "lint:fix": "eslint . --ext .ts --fix"
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0",
     "axios": "^1.6.8",
     "tiny-async-pool": "^2.1.0"
   },