@ogcio/o11y-sdk-react 0.1.0-beta.2

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0-beta.2](https://github.com/ogcio/o11y/compare/@ogcio/o11y-sdk-react@v0.1.0-beta.1...@ogcio/o11y-sdk-react@v0.1.0-beta.2) (2025-01-28)
+
+
+### Features
+
+* o11y sdk repo setup ([#15](https://github.com/ogcio/o11y/issues/15)) ([c5816ba](https://github.com/ogcio/o11y/commit/c5816baff1454353f12539949959e84964ed6401))

package/index.ts

@@ -0,0 +1,10 @@
+import {
+  Faro,
+  withFaroErrorBoundary,
+  withFaroProfiler,
+} from "@grafana/faro-react";
+import buildFaroInstrumentation from "./lib/instrumentation.faro.js";
+
+export * from "./lib/index.js";
+export { withFaroErrorBoundary, withFaroProfiler, Faro };
+export { buildFaroInstrumentation as instrumentFaro };

package/lib/index.ts

@@ -0,0 +1,48 @@
+interface SDKConfig {
+  /**
+   * The opentelemetry collector entrypoint GRPC url.
+   * If the collectoUrl is null or undefined, the instrumentation will not be activated.
+   * @example http://alloy:4317
+   */
+  collectorUrl: string;
+  /**
+   * Name of your application used for the collector to group logs
+   */
+  serviceName?: string;
+  /**
+   * Diagnostic log level for the internal runtime instrumentation
+   *
+   * @type string
+   * @default INFO
+   */
+  diagLogLevel?: SDKLogLevel;
+  /**
+   * Collector signals processing mode.
+   * signle: makes an http/grpc request for each signal and it is immediately processed inside grafana
+   * batch: sends multiple signals within a time window, optimized to reduce http/grpc calls in production
+   *
+   * @type string
+   * @default batch
+   */
+  collectorMode?: SDKCollectorMode;
+}
+
+export interface FaroSDKConfig extends SDKConfig {
+  /**
+   * String with single or multiple URLs separated by comma used by the instrumentation to ignore CORS errors and send signals through it
+   * @example http://localhost:9000,http://localhost:8000
+   * @example http://localhost:9000
+   */
+  corsTraceHeaders?: string;
+}
+
+export type SDKCollectorMode = "single" | "batch";
+
+export type SDKLogLevel =
+  | "NONE"
+  | "ERROR"
+  | "WARN"
+  | "INFO"
+  | "DEBUG"
+  | "VERBOSE"
+  | "ALL";

package/lib/instrumentation.faro.ts

@@ -0,0 +1,84 @@
+import type { FaroSDKConfig } from "./index.js";
+import {
+  ErrorsInstrumentation,
+  getWebInstrumentations,
+  initializeFaro,
+  WebVitalsInstrumentation,
+  type Faro,
+} from "@grafana/faro-react";
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import isUrl from "is-url";
+import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
+import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
+import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
+import { TracingInstrumentation } from "@grafana/faro-web-tracing";
+
+export default function buildFaroInstrumentation(
+  config?: FaroSDKConfig,
+): Faro | undefined {
+  if (!config) {
+    console.warn(
+      "observability config not set. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    return;
+  }
+
+  if (!config.collectorUrl) {
+    console.warn(
+      "collectorUrl not set. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    return;
+  }
+
+  if (!isUrl(config.collectorUrl)) {
+    console.error(
+      "collectorUrl does not use a valid format. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    return;
+  }
+
+  try {
+    diag.setLogger(
+      new DiagConsoleLogger(),
+      config.diagLogLevel
+        ? DiagLogLevel[config.diagLogLevel]
+        : DiagLogLevel.INFO,
+    );
+
+    const faro = initializeFaro({
+      url: config.collectorUrl,
+      app: {
+        name: config.serviceName,
+      },
+      batching: {
+        enabled: !(config.collectorMode === "single"),
+      },
+      instrumentations: [
+        ...getWebInstrumentations({
+          captureConsole: true,
+        }),
+
+        new ErrorsInstrumentation(),
+        new WebVitalsInstrumentation(),
+        new TracingInstrumentation({
+          propagator: new W3CTraceContextPropagator(),
+          instrumentations: [
+            new DocumentLoadInstrumentation(),
+            new FetchInstrumentation({
+              ignoreUrls: [config.collectorUrl], // ignore collector to avoid fetch loop
+              propagateTraceHeaderCorsUrls: config.corsTraceHeaders
+                ? config.corsTraceHeaders.split(",").map((s) => new RegExp(s))
+                : undefined,
+            }),
+            new UserInteractionInstrumentation(),
+          ],
+        }),
+      ],
+    });
+    console.log("Faro OpenTelemetry instrumentation started successfully.");
+    return faro;
+  } catch (error) {
+    console.error("Error starting Faro OpenTelemetry instrumentation:", error);
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@ogcio/o11y-sdk-react",
+  "version": "0.1.0-beta.2",
+  "description": "Opentelemetry standard instrumentation SDK for React based project",
+  "main": "dist/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js"
+  },
+  "keywords": [
+    "observability",
+    "o11y",
+    "opentelemetry",
+    "faro",
+    "react",
+    "ogcio"
+  ],
+  "author": "team:ogcio/observability",
+  "license": "ISC",
+  "dependencies": {
+    "@grafana/faro-react": "^1.12.3",
+    "@grafana/faro-web-sdk": "^1.12.3",
+    "@grafana/faro-web-tracing": "^1.12.3",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "1.30.1",
+    "@opentelemetry/instrumentation-document-load": "^0.44.0",
+    "@opentelemetry/instrumentation-fetch": "^0.57.1",
+    "@opentelemetry/instrumentation-user-interaction": "^0.44.0",
+    "is-url": "^1.2.4"
+  },
+  "devDependencies": {
+    "@types/is-url": "^1.2.32",
+    "@types/node": "^22.12.0",
+    "@vitest/coverage-v8": "^3.0.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.4"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest"
+  }
+}

package/test/index.test.ts

@@ -0,0 +1,28 @@
+import { describe, test, expect, vi } from "vitest";
+import { FaroSDKConfig } from "../lib";
+import { instrumentFaro } from "../index";
+
+vi.mock("../lib/instrumentation.faro", () => ({
+  default: vi.fn(),
+}));
+
+describe("instrumentFaro", () => {
+  test("should call buildFaroInstrumentation with the provided config", async () => {
+    const config: FaroSDKConfig = {
+      serviceName: "custom-service",
+      collectorUrl: "http://custom-collector.com",
+    };
+
+    const buildFaroInstrumentation = await import(
+      "../lib/instrumentation.faro"
+    );
+
+    instrumentFaro(config);
+
+    expect(buildFaroInstrumentation.default).toHaveBeenCalledWith(config);
+  });
+
+  test("should not throw when called without arguments", () => {
+    expect(() => instrumentFaro()).not.toThrow();
+  });
+});

package/test/validation.test.ts

@@ -0,0 +1,65 @@
+import { test, describe, assert, vi, expect } from "vitest";
+import buildFaroInstrumentation from "../lib/instrumentation.faro.js";
+import { Faro } from "@grafana/faro-react";
+import { instrumentFaro } from "../index.js";
+
+describe("validation config: should return without breaking the execution", () => {
+  test("should call buildFaroInstrumentation without config and skip instrumentation", async () => {
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(vi.fn());
+
+    instrumentFaro();
+
+    expect(consoleWarnSpy).toHaveBeenCalled();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "observability config not set. Skipping Faro OpenTelemetry instrumentation.",
+    );
+  });
+
+  test("faro instrumentation: url undefined", () => {
+    let sdk: Faro | undefined = undefined;
+
+    const consoleWarnSpy = vi
+      .spyOn(console, "warn")
+      .mockImplementation(vi.fn());
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(vi.fn());
+
+    assert.doesNotThrow(() => {
+      sdk = buildFaroInstrumentation({
+        collectorUrl: undefined!,
+      });
+    });
+
+    assert.equal(sdk, undefined);
+
+    expect(consoleWarnSpy).toHaveBeenCalled();
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      "collectorUrl not set. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+
+  test("faro instrumentation: invalid url", () => {
+    let sdk: Faro | undefined = undefined;
+
+    const consoleErrorSpy = vi
+      .spyOn(console, "error")
+      .mockImplementation(vi.fn());
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(vi.fn());
+
+    assert.doesNotThrow(() => {
+      sdk = buildFaroInstrumentation({
+        collectorUrl: "notavalidURL",
+      });
+    });
+
+    assert.equal(sdk, undefined);
+
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "collectorUrl does not use a valid format. Skipping Faro OpenTelemetry instrumentation.",
+    );
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+    "module": "NodeNext" /* Specify what module code is generated. */,
+    "outDir": "./dist" /* Specify an output folder for all emitted files. */,
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */,
+    "forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+    "strict": true /* Enable all strict type-checking options. */,
+    "skipLibCheck": true /* Skip type checking all .d.ts files. */,
+    "declaration": true
+  },
+  "exclude": ["**/test/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    watch: false,
+    include: ["**/test/*.test.ts"],
+    exclude: ["**/fixtures/**", "**/dist/**"],
+    poolOptions: {
+      threads: {
+        maxThreads: 8,
+      },
+    },
+    clearMocks: true,
+    testTimeout: 30_000,
+    coverage: {
+      enabled: true,
+      provider: "v8",
+      reportsDirectory: "coverage",
+      reporter: ["lcov", "cobertura"],
+      clean: true,
+    },
+    reporters: ["default", ["junit", { outputFile: "test-report.xml" }]],
+    environment: "node",
+  },
+});