feat: otel

Author: TheOutdoorProgrammer

.env.example

@@ -0,0 +1,12 @@
+# OpenTelemetry Configuration
+# Set the OTLP endpoint to enable tracing (omit to disable tracing)
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# Optional: Service identification
+OTEL_SERVICE_NAME=manifestsio
+OTEL_SERVICE_VERSION=0.1.0
+OTEL_DEPLOYMENT_ENVIRONMENT=development
+
+# Optional: Additional headers for OTLP exporter (comma-separated key=value pairs)
+# Example for authentication: OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer token123,X-Custom-Header=value
+# OTEL_EXPORTER_OTLP_HEADERS=

.gitignore

@@ -26,6 +26,7 @@ yarn-error.log*
 .pnpm-debug.log*
 
 # local env files
+.env
 .env*.local
 
 # vercel

README.md

@@ -13,6 +13,65 @@ Easy to use online kubernetes documentation.
 
 You can support more kubernetes versions by dropping any k8s version's [Open API spec](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json) into `oaspec/kubernetes` and updating `lib/oaspec.tsx`.
 
+## OpenTelemetry Tracing
+
+This project includes OpenTelemetry instrumentation for distributed tracing. Tracing is **disabled by default** and requires configuration to enable.
+
+### Local Development
+
+To enable tracing locally:
+
+1. Copy `.env.example` to `.env`
+2. Set the `OTEL_EXPORTER_OTLP_ENDPOINT` to your OTLP collector endpoint:
+   ```bash
+   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+   OTEL_SERVICE_NAME=manifestsio
+   OTEL_DEPLOYMENT_ENVIRONMENT=development
+   ```
+3. Start your application with `yarn dev`
+
+If `OTEL_EXPORTER_OTLP_ENDPOINT` is not set or empty, tracing will be disabled automatically.
+
+### Production Deployment
+
+For Kubernetes deployments, configure the environment variables in `deployment.yaml`:
+
+```yaml
+env:
+  - name: OTEL_EXPORTER_OTLP_ENDPOINT
+    value: "http://otel-collector.observability.svc.cluster.local:4318"
+  - name: OTEL_SERVICE_NAME
+    value: "manifestsio"
+  - name: OTEL_DEPLOYMENT_ENVIRONMENT
+    value: "production"
+```
+
+### What's Instrumented
+
+The application automatically traces:
+- **HTTP requests** - All incoming requests to the Next.js server
+- **Spec loading** - OpenAPI spec fetch operations (`oaspecFetch`)
+- **Server-side rendering** - Page rendering with `getServerSideProps`
+
+Custom spans include attributes like:
+- `manifestsio.item` - The product being viewed (e.g., "kubernetes")
+- `manifestsio.version` - The version being viewed (e.g., "1.34")
+- `manifestsio.resource` - The specific resource being viewed (e.g., "Pod")
+
+### Testing with Jaeger
+
+For local testing, you can run Jaeger all-in-one:
+
+```bash
+docker run -d --name jaeger \
+  -e COLLECTOR_OTLP_ENABLED=true \
+  -p 16686:16686 \
+  -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+```
+
+Then set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` in your `.env` file and access the Jaeger UI at http://localhost:16686.
+
 # Supporting new k8s/product versions
 
 ### New kubernetes versions

deployment.yaml

@@ -23,6 +23,21 @@ spec:
           image: <IMAGE>
           ports:
             - containerPort: 3000
+          env:
+            # OpenTelemetry Configuration
+            # Set OTEL_EXPORTER_OTLP_ENDPOINT to enable tracing
+            # Example: http://otel-collector.observability.svc.cluster.local:4318
+            - name: OTEL_EXPORTER_OTLP_ENDPOINT
+              value: ""  # Set to your OTLP endpoint or leave empty to disable tracing
+            - name: OTEL_SERVICE_NAME
+              value: "manifestsio"
+            - name: OTEL_SERVICE_VERSION
+              value: "0.1.0"
+            - name: OTEL_DEPLOYMENT_ENVIRONMENT
+              value: "production"
+            # Optional: Add authentication headers if required
+            # - name: OTEL_EXPORTER_OTLP_HEADERS
+            #   value: "Authorization=Bearer token123"
 ---
 apiVersion: v1
 kind: Service

instrumentation.ts

@@ -0,0 +1,65 @@
+export async function register() {
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    const { NodeSDK } = await import('@opentelemetry/sdk-node');
+    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
+    const { Resource } = await import('@opentelemetry/resources');
+    const {
+      ATTR_SERVICE_NAME,
+      ATTR_SERVICE_VERSION,
+      ATTR_DEPLOYMENT_ENVIRONMENT,
+    } = await import('@opentelemetry/semantic-conventions');
+    const { getNodeAutoInstrumentations } = await import('@opentelemetry/auto-instrumentations-node');
+
+    // Only initialize if OTLP endpoint is configured
+    const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (!otlpEndpoint) {
+      console.log('OpenTelemetry: OTEL_EXPORTER_OTLP_ENDPOINT not set, tracing disabled');
+      return;
+    }
+
+    const sdk = new NodeSDK({
+      resource: new Resource({
+        [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || 'manifestsio',
+        [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || '0.1.0',
+        [ATTR_DEPLOYMENT_ENVIRONMENT]: process.env.OTEL_DEPLOYMENT_ENVIRONMENT || 'development',
+      }),
+      traceExporter: new OTLPTraceExporter({
+        url: `${otlpEndpoint}/v1/traces`,
+        headers: process.env.OTEL_EXPORTER_OTLP_HEADERS
+          ? Object.fromEntries(
+              process.env.OTEL_EXPORTER_OTLP_HEADERS.split(',').map(header => {
+                const [key, value] = header.split('=');
+                return [key.trim(), value.trim()];
+              })
+            )
+          : {},
+      }),
+      instrumentations: [
+        getNodeAutoInstrumentations({
+          // Disable fs instrumentation to reduce noise from Next.js file system operations
+          '@opentelemetry/instrumentation-fs': {
+            enabled: false,
+          },
+          // Configure HTTP instrumentation to capture useful headers
+          '@opentelemetry/instrumentation-http': {
+            requestHook: (span, request) => {
+              span.setAttribute('http.user_agent', request.headers['user-agent'] || 'unknown');
+            },
+          },
+        }),
+      ],
+    });
+
+    sdk.start();
+    console.log('OpenTelemetry: Tracing initialized successfully');
+
+    // Graceful shutdown
+    process.on('SIGTERM', () => {
+      sdk
+        .shutdown()
+        .then(() => console.log('OpenTelemetry: Tracing terminated'))
+        .catch(error => console.error('OpenTelemetry: Error terminating tracing', error))
+        .finally(() => process.exit(0));
+    });
+  }
+}

lib/oaspec.tsx

@@ -1,4 +1,5 @@
 import {K8sDefinitions} from "@/typings/KubernetesSpec";
+import { trace, SpanStatusCode } from '@opentelemetry/api';
 
 import kubernetes134 from "../oaspec/kubernetes/1.34.json";
 import kubernetes133 from "../oaspec/kubernetes/1.33.json";
@@ -39,7 +40,31 @@ import spaceliftoperator010 from "../oaspec/spaceliftoperator/0.1.0.json";
 
 import spaceliftworkerpool0021 from "../oaspec/spaceliftworkerpool/0.0.21.json";
 
+const tracer = trace.getTracer('manifestsio-oaspec');
+
 export function oaspecFetch(item: string, version: string): K8sDefinitions {
+    return tracer.startActiveSpan('oaspec.fetch', (span) => {
+        span.setAttribute('oaspec.item', item);
+        span.setAttribute('oaspec.version', version);
+
+        try {
+            const result = fetchSpec(item, version);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        } catch (error) {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : 'Unknown error'
+            });
+            span.recordException(error as Error);
+            throw error;
+        } finally {
+            span.end();
+        }
+    });
+}
+
+function fetchSpec(item: string, version: string): K8sDefinitions {
     if (item === "kubernetes") {
         switch (version) {
             case "1.34":

next.config.js

@@ -2,6 +2,9 @@
 const nextConfig = {
   output: "standalone",
   reactStrictMode: true,
+  experimental: {
+    instrumentationHook: true,
+  },
   headers: async () => {
     return [
         {

package.json

@@ -13,6 +13,12 @@
     "@emotion/react": "^11.13.3",
     "@emotion/styled": "^11.13.0",
     "@next/font": "14.2.15",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.52.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.56.0",
+    "@opentelemetry/resources": "^1.29.0",
+    "@opentelemetry/sdk-node": "^0.56.0",
+    "@opentelemetry/semantic-conventions": "^1.29.0",
     "@types/node": "22.9.1",
     "@types/react": "18.3.12",
     "@types/react-dom": "18.3.1",

pages/[item]/[version]/[resource]/index.tsx

@@ -8,6 +8,7 @@ import ManifestsHeading from "@/components/ManifestsHeading";
 import {NextParsedUrlQuery} from "next/dist/server/request-meta";
 import {K8sDefinitions, K8sProperty, K8sPropertyArray} from "@/typings/KubernetesSpec";
 import {Resource} from "@/typings/Resource";
+import { trace, SpanStatusCode } from '@opentelemetry/api';
 
 type OtherVersions = {
     keys: Array<string>;
@@ -111,7 +112,11 @@ export default function Home({
     )
 }
 
+const tracer = trace.getTracer('manifestsio-pages');
+
 export const getServerSideProps: GetServerSideProps = async ({query}) => {
+    return tracer.startActiveSpan('getServerSideProps.resourceDetail', async (span) => {
+        try {
     function parseQuery(query: NextParsedUrlQuery) {
         let {item, version, resource, linked, oneOf, key} = query;
         if (Array.isArray(item) || !item) {
@@ -260,6 +265,10 @@ export const getServerSideProps: GetServerSideProps = async ({query}) => {
 
     const {item, version, resource, linked, oneOf, key} = parseQuery(query);
 
+    span.setAttribute('manifestsio.item', item);
+    span.setAttribute('manifestsio.version', version);
+    span.setAttribute('manifestsio.resource', resource);
+
     let spec = oaspecFetch(item, version);
 
     let linkedResource = defaultString(linked, popString(resource));
@@ -300,7 +309,19 @@ export const getServerSideProps: GetServerSideProps = async ({query}) => {
         props["oneOf"] = oneOfClicked;
     }
 
+    span.setStatus({ code: SpanStatusCode.OK });
     return {
         props
     }
+        } catch (error) {
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : 'Unknown error'
+            });
+            span.recordException(error as Error);
+            throw error;
+        } finally {
+            span.end();
+        }
+    });
 }