feat: tracing events

.changeset/great-chairs-worry.md

@@ -0,0 +1,6 @@
+---
+'@astrojs/opentelemetry': minor
+'astro': minor
+---
+
+Tracing hooks

.github/workflows/preview-release.yml

@@ -96,7 +96,7 @@ jobs:
         run: |
           packages=$(echo $AFFECTED_PACKAGES | jq -r '.[]' | tr '\n' ' ')
           if [ -n "$packages" ]; then
-            pnpm dlx pkg-pr-new publish --pnpm --compact --no-template $packages
+            pnpm dlx pkg-pr-new publish --pnpm --no-template $packages
           else
             echo "No affected packages to publish"
           fi

API-bash.md

@@ -0,0 +1,40 @@
+1. Pick a project:
+
+- Example: https://github.com/withastro/astro/tree/fryuni/tracing-hooks/examples/with-telemetry
+- New project
+- Existing project
+
+2. Use this version of Astro: https://pkg.pr.new/withastro/astro@fc5a126
+3. Add this integration: https://pkg.pr.new/withastro/astro/@astrojs/opentelemetry@fc5a126
+4. Add the integration to `astro.config.mjs/ts`:
+
+```ts
+import node from '@astrojs/node';
+import opentelemetry from '@astrojs/opentelemetry';
+export default defineConfig({
+  adapter: node({ mode: 'standalone' }),
+  integrations: [opentelemetry()],
+});
+```
+
+5. Start this docker compose: https://github.com/withastro/astro/blob/fryuni/tracing-hooks/examples/with-telemetry/docker-compose.yml
+
+   Or run `otel-tui`, if you have that installed.
+
+6. Have fun!
+
+## See the data
+
+Traces will be available on http://localhost:16686/
+
+Metrics will be availabe on http://localhost:9090/query
+
+Logs will be shown on the console
+
+## New APIs:
+
+```ts
+import tracer from 'astro:otel:tracer';
+import meter from 'astro:otel:meter';
+import logger from 'astro:otel:logger';
+```

examples/with-telemetry/astro.config.mts

@@ -0,0 +1,18 @@
+import node from '@astrojs/node';
+import opentelemetry from '@astrojs/opentelemetry';
+import svelte from '@astrojs/svelte';
+import { defineConfig } from 'astro/config';
+
+// https://astro.build/config
+export default defineConfig({
+	output: 'server',
+	adapter: node({
+		mode: 'standalone',
+	}),
+	integrations: [svelte(), opentelemetry()],
+	vite: {
+		build: {
+			sourcemap: true,
+		},
+	},
+});

examples/with-telemetry/docker-compose.yml

@@ -0,0 +1,31 @@
+volumes:
+  developmentData:
+    driver: local
+    driver_opts:
+      type: none
+      device: ./data/development
+
+services:
+  jaeger:
+    image: jaegertracing/all-in-one:1.71.0
+    ports:
+      - '6831:6831/udp'
+      - '16686:16686'
+
+  prometheus:
+    image: prom/prometheus
+    volumes:
+      - './prometheus.yaml:/etc/prometheus/prometheus.yml'
+    ports:
+      - '9090:9090'
+
+  otel:
+    image: otel/opentelemetry-collector-contrib:0.131.0
+    command: --config /config/otel.yaml
+    volumes:
+      - ./otel.yaml:/config/otel.yaml:ro
+    ports:
+      - '4317:4317'
+      - '4318:4318'
+      - '8888:8888'
+      - '8889:8889'

examples/with-telemetry/otel.yaml

@@ -0,0 +1,40 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+
+exporters:
+  otlp/jaeger:
+    endpoint: 'jaeger:4317'
+    tls:
+      insecure: true
+
+  prometheus:
+    endpoint: '0.0.0.0:8889'
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/jaeger]
+
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [prometheus]
+
+  telemetry:
+    metrics:
+      readers:
+        - pull:
+            exporter:
+              prometheus:
+                host: '0.0.0.0'
+                port: 8888

examples/with-telemetry/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@example/with-telemetry",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "server": "node dist/server/entry.mjs"
+  },
+  "dependencies": {
+    "@astrojs/node": "^9.3.3",
+    "@astrojs/opentelemetry": "0.0.1",
+    "@astrojs/svelte": "^7.1.0",
+    "@opentelemetry/api": "^1",
+    "@opentelemetry/sdk-node": "^0.203.0",
+    "astro": "^5.12.8",
+    "svelte": "^5.25.7"
+  }
+}

examples/with-telemetry/prometheus.yaml

@@ -0,0 +1,11 @@
+global:
+  scrape_interval: 10s
+scrape_configs:
+  - job_name: otel_collector
+    static_configs:
+      - targets:
+          - otel:8888
+  - job_name: app
+    static_configs:
+      - targets:
+          - otel:8889

examples/with-telemetry/src/api.ts

@@ -0,0 +1,90 @@
+import logger from 'astro:otel:logger';
+import meter from 'astro:otel:meter';
+import tracer from 'astro:otel:tracer';
+
+export interface Product {
+	id: number;
+	name: string;
+	price: number;
+	image: string;
+}
+
+interface User {
+	id: number;
+}
+
+interface Cart {
+	items: Array<{
+		id: number;
+		name: string;
+		count: number;
+	}>;
+}
+
+const readCounter = meter.createCounter('api.reads');
+
+async function getJson<T>(incomingReq: Request, endpoint: string): Promise<T> {
+	readCounter.add(1, { endpoint });
+
+	const origin = new URL(incomingReq.url).origin;
+	try {
+		const response = await fetch(`${origin}${endpoint}`, {
+			credentials: 'same-origin',
+			headers: incomingReq.headers,
+		});
+		if (!response.ok) {
+			throw new Error(`GET ${endpoint} failed: ${response.statusText}`);
+		}
+		return (await response.json()) as Promise<T>;
+	} catch (error) {
+		if (error instanceof DOMException || error instanceof TypeError) {
+			throw new Error(`GET ${endpoint} failed: ${error.message}`);
+		}
+		logger.emit({
+			severityText: 'error',
+			eventName: 'api.error',
+			body: {
+				message: `GET ${endpoint} failed: ${error instanceof Error ? error.message : String(error)}`,
+				endpoint,
+				stack: error instanceof Error ? error.stack : undefined,
+			},
+		});
+		throw error;
+	}
+}
+
+export function getProducts(incomingReq: Request): Promise<Product[]> {
+	return tracer.startActiveSpan('getProducts', () =>
+		getJson<Product[]>(incomingReq, '/api/products'),
+	);
+}
+
+export function getProduct(incomingReq: Request, id: number): Promise<Product> {
+	return tracer.startActiveSpan('getProduct', () =>
+		getJson<Product>(incomingReq, `/api/products/${id}`),
+	);
+}
+
+export function getUser(incomingReq: Request): Promise<User> {
+	return tracer.startActiveSpan('getUser', () => getJson<User>(incomingReq, `/api/user`));
+}
+
+export function getCart(incomingReq: Request): Promise<Cart> {
+	return tracer.startActiveSpan('getCart', () => getJson<Cart>(incomingReq, `/api/cart`));
+}
+
+export async function addToUserCart(id: number | string, name: string): Promise<void> {
+	await fetch(`${location.origin}/api/cart`, {
+		credentials: 'same-origin',
+		method: 'POST',
+		mode: 'no-cors',
+		headers: {
+			'Content-Type': 'application/json',
+			Cache: 'no-cache',
+		},
+		body: JSON.stringify({
+			id,
+			name,
+		}),
+	});
+}

examples/with-telemetry/src/components/AddToCart.svelte

@@ -0,0 +1,54 @@
+<script>
+	import { addToUserCart } from '../api';
+
+	let { id, name } = $props()
+
+	function notifyCartItem(id) {
+		window.dispatchEvent(new CustomEvent('add-to-cart', {
+			detail: id
+		}));
+	}
+
+	async function addToCart() {
+		await addToUserCart(id, name);
+		notifyCartItem(id);
+	}
+</script>
+<style>
+	button {
+  display:block;
+  padding:0.5em 1em 0.5em 1em;
+  border-radius:100px;
+  border:none;
+  font-size: 1.4em;
+  position:relative;
+  background:#0652DD;
+  cursor:pointer;
+  height:2em;
+  width:10em;
+  overflow:hidden;
+  transition:transform 0.1s;
+  z-index:1;
+}
+button:hover {
+  transform:scale(1.1);
+}
+
+.pretext {
+  color:#fff;
+  background:#0652DD;
+  position:absolute;
+  top:0;
+  left:0;
+  height:100%;
+  width:100%;
+  display:flex;
+  justify-content:center;
+  align-items:center;
+  font-family: 'Quicksand', sans-serif;
+	text-transform: uppercase;
+}
+</style>
+<button click={addToCart}>
+	<span class="pretext">Add to cart</span>
+</button>

examples/with-telemetry/src/components/Cart.svelte

@@ -0,0 +1,34 @@
+<script>
+	let { count } = $props()
+	let items = new Set();
+
+	function onAddToCart(ev) {
+		const id = ev.detail;
+		items.add(id);
+		count++;
+	}
+</script>
+<style>
+	.cart {
+		display: flex;
+		align-items: center;
+		text-decoration: none;
+		color: inherit;
+	}
+	.cart :first-child {
+		margin-right: 5px;
+	}
+
+	.cart-icon {
+		font-size: 36px;
+	}
+
+	.count {
+		font-size: 24px;
+	}
+</style>
+<svelte:window onadd-to-cart={onAddToCart}/>
+<a href="/cart" class="cart">
+	<span class="material-icons cart-icon">shopping_cart</span>
+	<span class="count">{count}</span>
+</a>

examples/with-telemetry/src/components/Container.astro

@@ -0,0 +1,13 @@
+---
+const { tag = 'div' } = Astro.props;
+const Tag = tag;
+---
+
+<style>
+	.container {
+		width: 1248px; /** TODO: responsive */
+		margin-left: auto;
+		margin-right: auto;
+	}
+</style>
+<Tag class="container"><slot /></Tag>