chore(js-sdk): add opentelemetry example app (#397)

Author: ewanharris

config/clients/js/config.overrides.json

@@ -119,11 +119,22 @@
       "destinationFilename": "example/example1/package.json",
       "templateType": "SupportingFiles"
     },
+    "example/opentelemetry/.npmrc": {},   
+    "example/opentelemetry/opentelemetry.mjs": {},
+    "example/opentelemetry/README.md": {},
+    "example/opentelemetry/instrumentation.mjs": {},
+    "example/opentelemetry/package.json.mustache": {
+      "destinationFilename": "example/opentelemetry/package.json",
+      "templateType": "SupportingFiles"
+    },
     ".madgerc": {},
     "telemetry.mustache": {
       "destinationFilename": "telemetry.ts",
       "templateType": "SupportingFiles"
     },
-    "docs/opentelemetry.md": {}
+    "docs/opentelemetry.md.mustache": {
+      "destinationFilename": "docs/opentelemetry.md",
+      "templateType": "SupportingFiles"
+    }
   }
 }

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

@@ -24,7 +24,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
         with:
           node-version: ${{ matrix.node-version }}
           registry-url: "https://registry.npmjs.org"
@@ -47,7 +47,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
         with:
           node-version: 20
           cache: "npm"
@@ -86,7 +86,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up node
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
         with:
           node-version: 20
           registry-url: "https://registry.npmjs.org"

config/clients/js/template/docs/opentelemetry.md renamed to config/clients/js/template/docs/opentelemetry.md.mustache

@@ -28,4 +28,8 @@ In cases when metrics events are sent, they will not be viewable outside of infr
 | `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                               |
+| `http.host`                    | `string` | Host identifier of the origin the request was sent to                               |
+
+## Example
+
+There is an [example project](https://{{gitHost}}/{{gitUserId}}/{{gitRepoId}}/blob/main/example/opentelemetry) that provides some guidance on how to configure OpenTelemetry available in the examples directory.

config/clients/js/template/example/README.md.mustache

@@ -6,6 +6,9 @@ A set of Examples on how to call the OpenFGA JS SDK
 Example 1:
 A bare-bones example. It creates a store, and runs a set of calls against it including creating a model, writing tuples and checking for access.
 
+OpenTelemetry:
+An example that demonstrates how to integrate the OpenFGA JS SDK with OpenTelemetry.
+
 ### Running the Examples
 
 Prerequisites:

config/clients/js/template/example/opentelemetry/.env.example

@@ -0,0 +1,11 @@
+# Configuration for OpenFGA
+FGA_CLIENT_ID=
+FGA_API_TOKEN_ISSUER=
+FGA_API_AUDIENCE=
+FGA_CLIENT_SECRET=
+FGA_STORE_ID=
+FGA_AUTHORIZATION_MODEL_ID=
+FGA_API_URL="http://localhost:8080"
+
+# Configuration for OpenTelemetry
+OTEL_SERVICE_NAME="openfga-opentelemetry-example"

config/clients/js/template/example/opentelemetry/.npmrc

@@ -0,0 +1 @@
+package-lock=false

config/clients/js/template/example/opentelemetry/README.md

@@ -0,0 +1,43 @@
+# OpenTelemetry usage with OpenFGA's JS SDK
+
+This example demonstrates how you can use OpenTelemetry with OpenFGA's JS SDK.
+
+## Prerequisites
+
+If you do not already have an OpenFGA instance running, you can start one using the following command:
+
+```bash
+docker run -d -p 8080:8080 openfga/openfga
+```
+
+You need to have an OpenTelemetry collector running to receive data. A pre-configured collector is available using Docker:
+
+```bash
+git clone https://github.com/ewanharris/opentelemetry-collector-dev-setup.git
+cd opentelemetry-collector-dev-setup
+docker-compose up -d
+```
+
+## Configure the example
+
+You need to configure the example for your environment:
+
+```bash
+cp .env.example .env
+```
+
+Now edit the `.env` file and set the values as appropriate.
+
+## Running the example
+
+Begin by installing the required dependencies:
+
+```bash
+npm i
+```
+
+Next, run the example:
+
+```bash
+npm start
+```

config/clients/js/template/example/opentelemetry/instrumentation.mjs

@@ -0,0 +1,25 @@
+import "dotenv/config";
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
+import process from "process";
+
+const sdk = new NodeSDK({
+  metricReader: new PeriodicExportingMetricReader({
+    exportIntervalMillis: 5000,
+    exporter: new OTLPMetricExporter({
+      concurrencyLimit: 1,
+    }),
+  }),
+});
+sdk.start();
+
+process.on("exit", () => {
+  sdk
+    .shutdown()
+    .then(
+      () => console.log("SDK shut down successfully"),
+      (err) => console.log("Error shutting down SDK", err)
+    )
+    .finally(() => process.exit(0));
+});

config/clients/js/template/example/opentelemetry/opentelemetry.mjs

@@ -0,0 +1,80 @@
+import "dotenv/config";
+import { CredentialsMethod, FgaApiValidationError, OpenFgaClient } from "@openfga/sdk";
+
+let credentials;
+if (process.env.FGA_CLIENT_ID) {
+  credentials = {
+    method: CredentialsMethod.ClientCredentials,
+    config: {
+      clientId: process.env.FGA_CLIENT_ID,
+      clientSecret: process.env.FGA_CLIENT_SECRET,
+      apiAudience: process.env.FGA_API_AUDIENCE,
+      apiTokenIssuer: process.env.FGA_API_TOKEN_ISSUER
+    }
+  };
+}
+
+const fgaClient = new OpenFgaClient({
+  apiUrl: process.env.FGA_API_URL,
+  storeId: process.env.FGA_STORE_ID,
+  authorizationModelId: process.env.FGA_MODEL_ID,
+  credentials
+});
+
+async function main () {
+
+  setTimeout(async () => {
+    try {
+      await main();
+    } catch (error) {
+      console.log(error);
+    }
+  }, 20000);
+
+  console.log("Reading Authorization Models");
+  const { authorization_models } = await fgaClient.readAuthorizationModels();
+  console.log(`Models Count: ${authorization_models.length}`);
+
+  console.log("Reading Tuples");
+  const { tuples } = await fgaClient.read();
+  console.log(`Tuples count: ${tuples.length}`);
+
+
+  const checkRequests = Math.floor(Math.random() * 10);
+  console.log(`Making ${checkRequests} checks`);
+  for (let index = 0; index < checkRequests; index++) {
+    console.log("Checking for access" + index);
+    try {
+      const { allowed } = await fgaClient.check({
+        user: "user:anne",
+        relation: "owner",
+        object: "folder:foo"
+      });
+      console.log(`Allowed: ${allowed}`);
+    } catch (error) {
+      if (error instanceof FgaApiValidationError) {
+        console.log(`Failed due to ${error.apiErrorMessage}`);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  console.log("writing tuple");
+  await fgaClient.write({
+    writes: [
+      {
+        user: "user:anne",
+        relation: "owner",
+        object: "folder:date-"+Date.now(),
+      }
+    ]
+  });
+}
+
+
+main()
+  .catch(error => {
+    console.error(`error: ${error}`);
+    process.exitCode = 1;
+  });

config/clients/js/template/example/opentelemetry/package.json.mustache

@@ -0,0 +1,22 @@
+{
+  "name": "openfga-opentelemetry-example",
+  "private": "true",
+  "version": "1.0.0",
+  "description": "A bare bones example of using the OpenFGA SDK with OpenTelemetry metrics reporting",
+  "author": "OpenFGA",
+  "license": "Apache-2.0",
+  "scripts": {
+    "start": "node --import ./instrumentation.mjs opentelemetry.mjs"
+  },
+  "dependencies": {
+    "@openfga/sdk": "^{{packageVersion}}",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.52.1",
+    "@opentelemetry/exporter-prometheus": "^0.52.1",
+    "@opentelemetry/sdk-metrics": "^1.25.1",
+    "@opentelemetry/sdk-node": "^0.52.1",
+    "dotenv": "^16.4.5"
+  },
+  "engines": {
+    "node": ">=16.13.0"
+  }
+}