(Documentation) Add documentation for OTEL ad Prometheus

_data/docs/latest.yaml

@@ -32,6 +32,22 @@ documentation:
             path: /guides/migration/from-0.6-to-1.0/
           - name: Migrating from 1.x to 2.0
             path: /guides/migration/from-1.x-to-2.0/
+      - name: Using OpenTelemetry
+        path: /guides/open-telemetry/
+        pages:
+          - name: Overview
+            path: /guides/open-telemetry/overview/
+          - name: NodeJS
+            path: /guides/open-telemetry/node-js/
+          - name: Python
+            path: /guides/open-telemetry/python/
+          - name: Go
+            path: /guides/open-telemetry/go/
+      - name: Using Prometheus
+        path: /guides/prometheus/
+        pages:
+          - name: Instructions
+            path: /guides/prometheus/instructions/
 
   - name: Core Concepts
     path: /core/

assets/css/prism.css

@@ -1,5 +1,5 @@
-/* PrismJS 1.23.0
-https://prismjs.com/download.html#themes=prism-tomorrow&languages=markup+css+clike+javascript+bash+groovy+java+javadoc+javadoclike+json+kotlin+scala&plugins=line-highlight+line-numbers+normalize-whitespace */
+/* PrismJS 1.24.1
+https://prismjs.com/download.html#themes=prism-tomorrow&languages=markup+css+clike+javascript+bash+go+groovy+java+javadoc+javadoclike+json+kotlin+markup-templating+php+python+scala+typescript+yaml&plugins=line-highlight+line-numbers+normalize-whitespace */
 /**
  * prism.js tomorrow night eighties for JavaScript, CoffeeScript, CSS and HTML
  * Based on https://github.com/chriskempson/tomorrow-theme

docs/latest/examples/guides/install/otel-go/deps.sh

@@ -0,0 +1,6 @@
+//tag:otel-deps:start
+go get go.opentelemetry.io/[email protected] \
+       go.opentelemetry.io/otel/[email protected] \
+       go.opentelemetry.io/otel/[email protected] \
+       go.opentelemetry.io/otel/exporters/otlp/otlptrace/[email protected]
+//tag:otel-deps:end

docs/latest/examples/guides/install/otel-go/main.go

@@ -0,0 +1,93 @@
+//tag:go-example:start
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+func handleErr(err error, message string) {
+	if err != nil {
+		log.Fatalf("%s: %v", message, err)
+	}
+}
+
+func initProvider() func() {
+	ctx := context.Background()
+
+	res, err := resource.New(ctx,
+		resource.WithAttributes(
+			// Update the name to match your desired service name
+			semconv.ServiceNameKey.String("otel-go-service"),
+		),
+	)
+	handleErr(err, "failed to create resource")
+
+	// Set up a trace exporter
+	traceExporter, err := otlptracehttp.New(ctx,
+		otlptracehttp.WithEndpoint("otel.apm.kamon.io"),
+		// Set your API key here
+		otlptracehttp.WithHeaders(map[string]string {
+			"x-kamon-apikey": "YOUR_API_KEY",
+		}),
+	)
+	handleErr(err, "failed to create trace exporter")
+
+	// Register the trace exporter with a TracerProvider, using a batch
+	// span processor to aggregate spans before export.
+	bsp := sdktrace.NewBatchSpanProcessor(traceExporter)
+	tracerProvider := sdktrace.NewTracerProvider(
+		sdktrace.WithSampler(sdktrace.AlwaysSample()),
+		sdktrace.WithResource(res),
+		sdktrace.WithSpanProcessor(bsp),
+	)
+	otel.SetTracerProvider(tracerProvider)
+
+	// set global propagator to tracecontext (the default is no-op).
+	otel.SetTextMapPropagator(propagation.TraceContext{})
+
+	return func() {
+		// Shutdown will flush any remaining spans and shut down the exporter.
+		handleErr(tracerProvider.Shutdown(ctx), "failed to shutdown TracerProvider")
+	}
+}
+
+//tag:app:start
+func main() {
+	log.Printf("Waiting for connection...")
+
+	shutdown := initProvider()
+	defer shutdown()
+
+	tracer := otel.Tracer("test-tracer")
+
+	// work begins
+	ctx, span := tracer.Start(
+		context.Background(),
+		"CollectorExporter-Example",
+		trace,
+	)
+	defer span.End()
+	for i := 0; i < 10; i++ {
+		_, iSpan := tracer.Start(ctx, fmt.Sprintf("Sample-%d", i))
+		log.Printf("Doing really hard work (%d / 10)\n", i+1)
+
+		<-time.After(time.Second)
+		iSpan.End()
+	}
+
+	log.Printf("Done!")
+}
+//tag:app:end
+//tag:go-example:end

docs/latest/examples/guides/install/otel-go/setup.go

@@ -0,0 +1,63 @@
+//tag:setup:start
+package main
+
+import (
+	"context"
+	"log"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
+	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
+	"go.opentelemetry.io/otel/propagation"
+	"go.opentelemetry.io/otel/sdk/resource"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+	semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
+	"go.opentelemetry.io/otel/trace"
+)
+
+func handleErr(err error, message string) {
+	if err != nil {
+		log.Fatalf("%s: %v", message, err)
+	}
+}
+
+func initProvider() func() {
+	ctx := context.Background()
+
+	res, err := resource.New(ctx,
+		resource.WithAttributes(
+			// Update the name to match your desired service name
+			semconv.ServiceNameKey.String("otel-go-service"),
+		),
+	)
+	handleErr(err, "failed to create resource")
+
+	// Set up a trace exporter
+	traceExporter, err := otlptracehttp.New(ctx,
+		otlptracehttp.WithEndpoint("otel.apm.kamon.io"),
+		otlptracehttp.WithHeaders(map[string]string {
+			// Set your API key here
+			"x-kamon-apikey": "YOUR_API_KEY",
+		}),
+	)
+	handleErr(err, "failed to create trace exporter")
+
+	// Register the trace exporter with a TracerProvider, using a batch
+	// span processor to aggregate spans before export.
+	bsp := sdktrace.NewBatchSpanProcessor(traceExporter)
+	tracerProvider := sdktrace.NewTracerProvider(
+		sdktrace.WithSampler(sdktrace.AlwaysSample()),
+		sdktrace.WithResource(res),
+		sdktrace.WithSpanProcessor(bsp),
+	)
+	otel.SetTracerProvider(tracerProvider)
+
+	// set global propagator to tracecontext (the default is no-op).
+	otel.SetTextMapPropagator(propagation.TraceContext{})
+
+	return func() {
+		// Shutdown will flush any remaining spans and shut down the exporter.
+		handleErr(tracerProvider.Shutdown(ctx), "failed to shutdown TracerProvider")
+	}
+}
+//tag:setup:end

docs/latest/examples/guides/install/otel-node/app.js

@@ -0,0 +1,36 @@
+// tag:app:start
+// Has to be called first for instrumentation to work!
+require("./instrumentation");
+
+const express = require("express");
+const axios = require("axios");
+
+const app = express();
+
+app.get("/db-status", (_req, res) => {
+  res.send("database ok");
+});
+
+app.get("/api-status", (_req, res) => {
+  res.send("api ok");
+});
+
+app.get("/status", async (_req, res) => {
+  const [db, api] = await Promise.all([
+    axios
+      .get("http://localhost:8080/db-status")
+      .then((result) => result.data)
+      .catch(() => "db not responding"),
+    axios
+      .get("http://localhost:8080/api-status")
+      .then((result) => result.data)
+      .catch(() => "api not responding"),
+  ]);
+
+  res.send(`(${db}, ${api})`);
+});
+
+app.listen(8080, () => {
+  console.log("server listening on port 8080");
+});
+// tag:app:end

docs/latest/examples/guides/install/otel-node/app.ts

@@ -0,0 +1,36 @@
+// tag:app:start
+// Has to be called first for instrumentation to work!
+import "./instrumentation";
+
+import express from "express";
+import axios from "axios";
+
+const app = express();
+
+app.get("/db-status", (_req, res) => {
+  res.send("database ok");
+});
+
+app.get("/api-status", (_req, res) => {
+  res.send("api ok");
+});
+
+app.get("/status", async (_req, res) => {
+  const [db, api] = await Promise.all([
+    axios
+      .get("http://localhost:8080/db-status")
+      .then((result) => result.data)
+      .catch(() => "db not responding"),
+    axios
+      .get("http://localhost:8080/api-status")
+      .then((result) => result.data)
+      .catch(() => "api not responding"),
+  ]);
+
+  res.send(`(${db}, ${api})`);
+});
+
+app.listen(8080, () => {
+  console.log("server listening on port 8080");
+});
+// tag:app:end

docs/latest/examples/guides/install/otel-node/instrumentation.js

@@ -0,0 +1,48 @@
+// tag:instrumentation:start
+const { diag, DiagConsoleLogger, DiagLogLevel } = require("@opentelemetry/api");
+const { NodeTracerProvider } = require("@opentelemetry/node");
+const { Resource } = require("@opentelemetry/resources");
+const { ResourceAttributes } = require("@opentelemetry/semantic-conventions");
+const { SimpleSpanProcessor } = require("@opentelemetry/tracing");
+const { registerInstrumentations } = require("@opentelemetry/instrumentation");
+const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
+const { ExpressInstrumentation } = require("@opentelemetry/instrumentation-express");
+const { CollectorTraceExporter } = require("@opentelemetry/exporter-collector-proto");
+const os = require("os");
+
+// Change to the service name you wish to use
+const serviceName = "my-otel-service";
+const host = os.hostname();
+
+const provider = new NodeTracerProvider({
+  resource: new Resource({
+    [ResourceAttributes.SERVICE_NAME]: serviceName,
+    [ResourceAttributes.HOST_NAME]: host,
+  })
+});
+
+// Adjust log level when running in production
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
+
+provider.addSpanProcessor(
+  new SimpleSpanProcessor(
+    new CollectorTraceExporter({
+      headers: {
+        // Enter your API key here
+        "x-kamon-apikey": "YOUR_API_KEY",
+      },
+      url: "https://otel.apm.kamon.io/v1/traces",
+      serviceName,
+    }),
+  ),
+);
+
+provider.register();
+
+registerInstrumentations({
+  instrumentations: [
+    new ExpressInstrumentation(),
+    new HttpInstrumentation(),
+  ],
+});
+// tag:instrumentation:end

docs/latest/examples/guides/install/otel-node/instrumentation.ts

@@ -0,0 +1,48 @@
+// tag:instrumentation:start
+import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
+import { NodeTracerProvider } from "@opentelemetry/node";
+import { Resource } from "@opentelemetry/resources";
+import { ResourceAttributes } from "@opentelemetry/semantic-conventions";
+import { SimpleSpanProcessor } from "@opentelemetry/tracing";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { CollectorTraceExporter } from "@opentelemetry/exporter-collector-proto";
+import os from "os";
+
+// Change to the service name you wish to use
+const serviceName = "my-otel-service";
+const host = os.hostname();
+
+const provider = new NodeTracerProvider({
+  resource: new Resource({
+    [ResourceAttributes.SERVICE_NAME]: serviceName,
+    [ResourceAttributes.HOST_NAME]: host,
+  })
+});
+
+// Adjust log level when running in production
+diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ALL);
+
+provider.addSpanProcessor(
+  new SimpleSpanProcessor(
+    new CollectorTraceExporter({
+      headers: {
+        // Enter your API key here
+        "x-kamon-apikey": "YOUR_API_KEY",
+      },
+      url: "https://otel.apm.kamon.io/v1/traces",
+      serviceName,
+    }),
+  ),
+);
+
+provider.register();
+
+registerInstrumentations({
+  instrumentations: [
+    new ExpressInstrumentation(),
+    new HttpInstrumentation(),
+  ],
+});
+// tag:instrumentation:end

docs/latest/examples/guides/install/otel-node/npm.sh

@@ -0,0 +1,9 @@
+// tag:otel-deps:start
+npm install \
+  @opentelemetry/api \
+  @opentelemetry/node \
+  @opentelemetry/instrumentation-http \
+  @opentelemetry/instrumentation-express \
+  @opentelemetry/tracing \
+  @opentelemetry/exporter-collector-proto
+// tag:otel-deps:end