Merge pull request #169 from oldbettie/quick-start-guide

quick start repo

.gitignore

@@ -36,12 +36,12 @@ bower_components
 
 # Compiled binary addons (https://nodejs.org/api/addons.html)
 build/Release
-
+.DS_Store
 # Dependency directories
 node_modules/
 jspm_packages/
 .pnpm-store
-
+.idea
 # TypeScript v1 declaration files
 typings/
 

README.md

@@ -4,13 +4,19 @@ An OpenTelemetry compatible library for instrumenting and exporting traces from
 
 ## Getting started
 
+```bash
+npm install @microlabs/otel-cf-workers @opentelemetry/api
+```
+
 > [!IMPORTANT]
 > To be able to use the Open Telemetry library you have to add the NodeJS compatibility flag in your `wrangler.toml` file.
 
 ```
 compatibility_flags = [ "nodejs_compat" ]
 ```
 
+For a simple setup example with configuration examples, have a look at the [Quickstart Example](https://github.com/evanderkoogh/otel-cf-workers/tree/main/examples/worker)
+
 ### Code example
 
 ```typescript

examples/quickstart/.dev.vars.sample

@@ -0,0 +1 @@
+HONEYCOMB_API_KEY=<honeycomb_api_key>

examples/quickstart/.gitignore

@@ -0,0 +1,172 @@
+# Logs
+
+logs
+_.log
+npm-debug.log_
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# Runtime data
+
+pids
+_.pid
+_.seed
+\*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+
+lib-cov
+
+# Coverage directory used by tools like istanbul
+
+coverage
+\*.lcov
+
+# nyc test coverage
+
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+
+bower_components
+
+# node-waf configuration
+
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+
+build/Release
+
+# Dependency directories
+
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+
+web_modules/
+
+# TypeScript cache
+
+\*.tsbuildinfo
+
+# Optional npm cache directory
+
+.npm
+
+# Optional eslint cache
+
+.eslintcache
+
+# Optional stylelint cache
+
+.stylelintcache
+
+# Microbundle cache
+
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+
+.node_repl_history
+
+# Output of 'npm pack'
+
+\*.tgz
+
+# Yarn Integrity file
+
+.yarn-integrity
+
+# dotenv environment variable files
+
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+
+.cache
+.parcel-cache
+
+# Next.js build output
+
+.next
+out
+
+# Nuxt.js build / generate output
+
+.nuxt
+dist
+
+# Gatsby files
+
+.cache/
+
+# Comment in the public line in if your project uses Gatsby and not Next.js
+
+# https://nextjs.org/blog/next-9-1#public-directory-support
+
+# public
+
+# vuepress build output
+
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+
+.temp
+.cache
+.idea
+# Docusaurus cache and generated files
+
+.docusaurus
+
+# Serverless directories
+
+.serverless/
+
+# FuseBox cache
+
+.fusebox/
+
+# DynamoDB Local files
+
+.dynamodb/
+
+# TernJS port file
+
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+
+.vscode-test
+
+# yarn v2
+
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.\*
+
+# wrangler project
+
+.dev.vars
+.wrangler/

examples/quickstart/QUICKSTART_GUIDE.md

@@ -0,0 +1,63 @@
+# Quickstart Guide
+
+This is a very simple example of how to get started with the OpenTelemetry cf-worker package.
+
+It wraps your worker in an OpenTelemetry span and sends it to Honeycomb.
+You just need to provide your Honeycomb API key as a secret.
+
+## Installation
+
+```bash
+npm install @microlabs/otel-cf-workers @opentelemetry/api
+npx wrangler secret put HONEYCOMB_API_KEY
+```
+
+And set the Node Compatibility flag by adding `compatibility_flags = [ "nodejs_compat" ]`
+in your `wrangler.toml`
+
+## Example
+
+```typescript
+import { instrument, ResolveConfigFn } from '@microlabs/otel-cf-workers'
+import { trace } from '@opentelemetry/api'
+
+export interface Env {
+	HONEYCOMB_API_KEY: string
+}
+
+const handler = {
+	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+		// Get the URL of the origin server
+		const url = new URL(request.url)
+		const originUrl = `https://${url.hostname}${url.pathname}${url.search}`
+
+		// Create a new request to the origin server
+		const originRequest = new Request(originUrl, {
+			method: request.method,
+			headers: request.headers,
+			body: request.body,
+		})
+
+		// Add tracing information
+		trace.getActiveSpan()?.setAttribute('origin_url', originUrl)
+
+		// Fetch from the origin server
+		// Return the response from the origin server
+		return await fetch(originRequest)
+	},
+}
+
+const config: ResolveConfigFn = (env: Env, _trigger: any) => {
+	return {
+		exporter: {
+			url: 'https://api.honeycomb.io/v1/traces',
+			headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+		},
+		service: { name: 'my-service-name' },
+	}
+}
+
+export default instrument(handler, config)
+```
+
+With this setup, you can run your worker as usual with `wrangler dev` or `wrangler run src/index.ts`.

examples/quickstart/package.json

@@ -0,0 +1,18 @@
+{
+	"name": "otel-quickstart-example",
+	"version": "0.0.0",
+	"private": true,
+	"scripts": {
+		"start": "wrangler dev",
+		"deploy": "wrangler publish"
+	},
+	"dependencies": {
+		"@microlabs/otel-cf-workers": "^1.0.0-rc.45",
+		"@opentelemetry/api": "^1.6.0"
+	},
+	"devDependencies": {
+		"@cloudflare/workers-types": "^4.20231016.0",
+		"typescript": "^5.2.2",
+		"wrangler": "^2.13.0"
+	}
+}

examples/quickstart/src/index.ts

@@ -0,0 +1,40 @@
+import { instrument, ResolveConfigFn } from '@microlabs/otel-cf-workers'
+import { trace } from '@opentelemetry/api'
+
+export interface Env {
+	HONEYCOMB_API_KEY: string
+}
+
+const handler = {
+	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+		// Get the URL of the origin server
+		const url = new URL(request.url)
+		const originUrl = `https://${url.hostname}${url.pathname}${url.search}`
+
+		// Create a new request to the origin server
+		const originRequest = new Request(originUrl, {
+			method: request.method,
+			headers: request.headers,
+			body: request.body,
+		})
+
+		// Add tracing information
+		trace.getActiveSpan()?.setAttribute('origin_url', originUrl)
+
+		// Fetch from the origin server
+		// Return the response from the origin server
+		return await fetch(originRequest)
+	},
+}
+
+const config: ResolveConfigFn = (env: Env, _trigger: any) => {
+	return {
+		exporter: {
+			url: 'https://api.honeycomb.io/v1/traces',
+			headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+		},
+		service: { name: 'my-service-name' },
+	}
+}
+
+export default instrument(handler, config)

examples/quickstart/tsconfig.json

@@ -0,0 +1,35 @@
+{
+	"compilerOptions": {
+		"target": "es2021" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+		"lib": [
+			"es2021"
+		] /* Specify a set of bundled library declaration files that describe the target runtime environment. */,
+		"jsx": "react" /* Specify what JSX code is generated. */,
+
+		/* Modules */
+		"module": "es2022" /* Specify what module code is generated. */,
+		"moduleResolution": "node" /* Specify how TypeScript looks up a file from a given module specifier. */,
+		"types": [
+			"@cloudflare/workers-types"
+		] /* Specify type package names to be included without being referenced in a source file. */,
+		"resolveJsonModule": true /* Enable importing .json files */,
+
+		/* JavaScript Support */
+		"allowJs": true /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */,
+		"checkJs": false /* Enable error reporting in type-checked JavaScript files. */,
+
+		/* Emit */
+		"noEmit": true /* Disable emitting files from a compilation. */,
+
+		/* Interop Constraints */
+		"isolatedModules": true /* Ensure that each file can be safely transpiled without relying on other imports. */,
+		"allowSyntheticDefaultImports": true /* Allow 'import x from y' when a module doesn't have a default export. */,
+		"forceConsistentCasingInFileNames": true /* Ensure that casing is correct in imports. */,
+
+		/* Type Checking */
+		"strict": true /* Enable all strict type-checking options. */,
+
+		/* Completeness */
+		"skipLibCheck": true /* Skip type checking all .d.ts files. */
+	}
+}

examples/quickstart/wrangler.toml

@@ -0,0 +1,8 @@
+#:schema node_modules/wrangler/config-schema.json
+name = "otel-quickstart-example"
+main = "src/index.ts"
+compatibility_date = "2024-09-09"
+compatibility_flags = [ "nodejs_compat" ]
+
+# [vars]
+HONEYCOMB_API_KEY = "example"

examples/worker/wrangler.toml

@@ -14,4 +14,4 @@ bindings = [
 
 [[migrations]]
 tag = "v1" # Should be unique for each entry
-new_classes = ["TestOtelDO"]
+new_classes = ["TestOtelDO"]