test scaffolding and DO storage instrumentation tests

.github/workflows/pr.yaml

@@ -0,0 +1,24 @@
+name: PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches: [main]
+  pull_request_target:
+    branches: [main]
+
+jobs:
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - name: Restore dependencies
+        run: npm ci
+      - name: Run tests
+        run: npm test:coverage

README.md

@@ -2,44 +2,269 @@
 
 An OpenTelemetry compatible library for instrumenting and exporting traces from Cloudflare Workers.
 
-> **Warning**
-> This package is still in alpha. It has not been tested extensively, optimisations have not yet been made, and the API interface and the configuration options are subject to change.
-
 ## Getting started
 
+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" ]
+```
+
+### Code example
+
 ```typescript
 import { trace } from '@opentelemetry/api'
-import { instrument, WorkerTraceConfig } from '@microlabs/otel-cf-worker'
+import { instrument, ResolveConfigFn } from '@microlabs/otel-cf-workers'
+
+export interface Env {
+	HONEYCOMB_API_KEY: string
+	OTEL_TEST: KVNamespace
+}
 
 const handler = {
 	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+		await fetch('https://cloudflare.com')
+
+		const greeting = "G'day World"
 		trace.getActiveSpan()?.setAttribute('greeting', greeting)
-		return new Response(`G'day World!`)
+		ctx.waitUntil(fetch('https://workers.dev'))
+		return new Response(`${greeting}!`)
 	},
 }
 
-const config: WorkerTraceConfig = {
-	exporter: { url: 'https://api.honeycomb.io/v1/traces' },
-	serviceName: 'greetings',
-	serviceVersion: '0.1',
+const config: ResolveConfigFn = (env: Env, _trigger) => {
+	return {
+		exporter: {
+			url: 'https://api.honeycomb.io/v1/traces',
+			headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+		},
+		service: { name: 'greetings' },
+	}
 }
 
 export default instrument(handler, config)
 ```
 
-If you need to send an API token to your Open Telemetry provider of your choice, you can either add a `headers` object in the exporter part of the configuration (not recommended), or set it was an environment secret in the form: `otel.headers.<header_name>` with the API token as the value.
+## Auto-instrumentation
 
-So for Honeycomb for example, the environment variable would be: `otel.headers.x-honeycomb-team`.
-Any other headers that you need to send through can be configured in either the config object or through environment variables.
+### Workers
 
-## Auto-instrumentation
+Wrapping your exporter handler with the `instrument` function is all you need to do to automatically have not just the functions of you handler auto-instrumented, but also the global `fetch` and `caches` and all of the supported bindings in your environment such as KV.
+
+See the quick start code sample for an example of how it works.
+
+### Durable Objects
+
+Instrumenting Durable Objects work very similar to the regular Worker auto-instrumentation. Instead of wrapping the handler in an `instrument` call, you wrap the Durable Object class with the `instrumentDO` function.
+
+```typescript
+import { instrumentDO, PartialTraceConfig } from '@microlabs/otel-cf-workers'
+
+const config: ResolveConfigFn = (env: Env, _trigger) => {
+	return {
+		exporter: {
+			url: 'https://api.honeycomb.io/v1/traces',
+			headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+		},
+		service: { name: 'greetings-do' },
+	}
+}
+
+class OtelDO implements DurableObject {
+	async fetch(request: Request): Promise<Response> {
+		return new Response('Hello World!')
+	}
+}
+
+const TestOtelDO = instrumentDO(OtelDO, doConfig)
+
+export { TestOtelDO }
+```
+
+## Creating custom spans
+
+While auto-instrumenting should take care of a lot of the information that you would want to add, there will always be application specific information you want to send along.
+
+You can get the current active span by doing:
+
+```typescript
+import {trace} from '@opentelemetry/api'
+
+const handler = {
+	async fetch(request: Request) {
+		const span = trace.getActiveSpan()
+		if(span) span.setAttributes('name', 'value')
+		....
+	}
+}
+```
+
+Or if you want to create a new span:
+
+```typescript
+import { trace } from '@opentelemetry/api'
+
+const handler = {
+	async fetch(request: Request) {
+		const tracer = trace.getTracer('my_own_tracer_name')
+		return tracer.startActiveSpan('name', (span) => {
+			const response = await doSomethingAwesome
+			span.end()
+			return response
+		})
+	},
+}
+```
+
+## Configuration
+
+For configuration you can either pass in a [TraceConfig](https://github.com/evanderkoogh/otel-cf-workers/blob/0da125a4e16ff13e49f8e486340eb6080e631eb9/src/types.ts#L24C18-L24C29) or a function that takes the Environment and the trigger for this particular trace and returns a `TraceConfig`.
+
+Because the configuration function is run separately for every new invocation, it is possible to tailor your configuration for every type of request. So it is for example possible to have a much lower sampling ratio for your healthchecks than actual API requests.
+
+### Exporter
+
+In the `exporter`, you need to configure where to send spans to. It can take either an instance of a class that implements the standard Open Telemetry `SpanExporter`interface, or an object with the properties `url` and optionally `headers` to configure an exporter for the Open Telemetry format.
+
+Examples:
+
+```typescript
+const exporter = new ConsoleSpanExporter()
+```
+
+```typescript
+const exporter = {
+	url: 'https://api.honeycomb.io/v1/traces',
+	headers: { 'x-honeycomb-team': env.HONEYCOMB_API_KEY },
+}
+```
+
+### Fetch
+
+`includeTraceContext` is used to specify if outgoing requests should include the TraceContext so that the other service can participate in a distributed trace.
+The default is `true` for all outgoing requests, but you can turn it off for all requests with `false`, or specify a method that takes the outgoing `Request` method and return a boolean on whether to include the tracing context.
 
-Currently only the fetch handler, outgoing `fetch` and KV bindings are auto-instrumented. The plan is to add support for all handlers (such as cron triggers or queue messages) and binding types (such as Durable Objects)
+Example:
+
+```typescript
+const fetchConf = (request: Request): boolean => {
+	return new URL(request.url).hostname === 'example.com'
+}
+```
+
+### Handlers
+
+The `handlers` field of the configuration overrides the way in which event handlers, such as `fetch` or `queue`, are instrumented.
+
+#### Fetch Handler
+
+`acceptTraceContext` is used to specify if incoming requests handled by `fetch` should accept a TraceContext and participate in a distributed trace.
+The default is `true` for all incoming requests, but you can turn it off for all requests with `false` or specify a method that takes the incoming `Request` and returns a boolean indicating whether to accept the tracing context.
+
+Example:
+
+```typescript
+const fetchConf = (request: Request): boolean => {
+	return new URL(request.url).hostname === 'example.com'
+}
+```
+
+### PostProcessor
+
+The PostProcessor function is called just before exporting the spans and allows you to make any changes to the spans before sending this. For example to remove entire spans, or to remove or redact security or privacy sensitive data.
+
+Example:
+
+```typescript
+const postProcessor = (spans: ReadableSpan[]): ReadableSpan[] => {
+	spans[0].attributes['http.url'] = 'REDACTED'
+	return spans
+}
+```
+
+### Sampling
+
+One of the challenges of tracing is that for sites and applications with a lot of traffic it becomes prohibitively expensive to store every trace. So the question becomes how to store the ones with the most interesting information and drop the ones that are the least interesting. That is where sampling comes in.
+
+#### Head Sampling vs Tail Sampling
+
+There are two (complimentary) sampling strategies: Head Sampling and Tail Sampling and in a lot of cases you will want to use a combination to get the most information into the least amount of sampled events.
+
+To understand the difference in head vs tail sampling in our context, we have to understand distributed tracing. A distributed trace is one that spans multiple systems or services. At every point another service is called, we inject a header with the information about the trace, such as the traceId, the parentSpanId and a hint if this trace is sampled.
+
+Head Sampling, as the name implies, is done at the beginning of a span/trace. In our case it is mostly used to signal to downstream systems whether or not to sample a particular trace, because we can always drop the current services portion of a trace during Tail Sampling.
+
+Head Sampling can be configured with any standard Open Telemetry `Sampler` or an object with a `ratio` property and optional `acceptRemote` property. The default is the AlwaysOnSampler, which samples every single request.
+
+Examples:
+
+```typescript
+const headSampler = new AlwaysOnSampler()
+```
+
+```typescript
+const headSampler = {
+	acceptRemote: false //Whether to accept incoming trace contexts
+	ratio: 0.5 //number between 0 and 1 that represents the ratio of requests to sample. 0 is none and 1 is all requests.
+}
+```
+
+Tail Sampling on the other hand is done at the end. Because we record every single span, even if it isn't head sampled, it is possible to still sample the local part of a trace in say the event of an error.
+
+Example:
+
+```typescript
+const tailSampler = (localTrace: LocalTrace): boolean => {
+	const localRootSpan = traceInfo.localRootSpan as unknown as ReadableSpan
+	return localRootSpan.spanContext().traceFlags === TraceFlags.SAMPLED
+}
+```
+
+The default is a tailSampler that samples traces that have been head sampled or if the local root span is marked as an error.
+
+#### Service
+
+Service identifies the service and version to help with querying.
+
+Example:
+
+```typescript
+const service = {
+	name: 'some_name' //required. The name of your service
+	version: '1.0.4' //optional: An opaque version string. Can be a semver or git hash for example
+	namespace: 'namespace' //optional: Useful to group multiple services together in one namespace.
+}
+```
 
 ## Distributed Tracing
 
-One of the advantages of using Open Telemetry is that it makes it easier to do distributed tracing through multiple different services. This library will automatically inject the W3C Trace Context headers when making outbound fetch calls.
+One of the advantages of using Open Telemetry is that it makes it easier to do distributed tracing through multiple different services. This library will automatically inject the W3C Trace Context headers when making calls to Durable Objects or outbound fetch calls.
+
+## Limitations
+
+- The worker runtime does not expose accurate timing information to protect against side-channel attacks such as Spectre and will only update the clock on IO, so any CPU heavy processing will look like it takes 0 milliseconds.
+- Not everything is auto-instrumented yet. See the lists below for what is and isn't.
+
+Triggers:
+
+- [x] HTTP (`handler.fetch`)
+- [x] Queue (`handler.queue`)
+- [ ] Cron (`handler.scheduled`)
+- [x] Durable Objects
+- [x] waitUntil (`ctx.waitUntil`)
+
+Globals/built-ins:
+
+- [x] Fetch
+- [x] Caches
+- [x] Durable Object Storage
 
-## Sampling
+Bindings:
 
-Sampling is currently not supported.
+- [x] KV
+- [x] Queue
+- [x] Durable Objects
+- [ ] R2
+- [ ] D1
+- [ ] Worker Bindings
+- [ ] Workers for Platform Dispatch

examples/queue/.dev.vars

@@ -0,0 +1 @@
+otel.headers.x-honeycomb-team=xACRoffXRK3ey8SgmNEJpH

examples/queue/README.md

@@ -0,0 +1,80 @@
+# Cloudflare Workers Template
+
+This template makes it easy to build and run [Cloudflare Workers](https://developers.cloudflare.com/workers/), which can be published to the [Cloudflare Global Network](https://www.cloudflare.com/network/), or run directly from Replit using `wrangler dev` (no Cloudflare account required). In the future, `wrangler dev` will be powered by [Workerd](https://github.com/cloudflare/workerd), our Open-Source Workers runtime.
+
+## Setup
+
+### Initialize a Workers project
+
+Click **Run** in your Replit workspace to set up a Workers project with customizable settings using [Wrangler](https://developers.cloudflare.com/workers/wrangler/). By default, it will initialize a Git repository, set up a TypeScript project, and create a Fetch handler.
+
+### Silence Wrangler metrics prompts
+
+Every time a Repl using the Workers Template is booted up, Wrangler will prompt for sending anonymous metrics to Cloudflare. To silence this prompt:
+
+1. Add a [Replit secret](https://docs.replit.com/programming-ide/storing-sensitive-information-environment-variables) with the name `WRANGLER_SEND_METRICS`.
+2. Use value `true` to send anonymous metrics to Cloudflare, or `false` to opt-out.
+
+## Develop and run in Replit
+
+After you have initialized your Workers project, select **Run** again to deploy your Worker in dev mode. The **Run** button in your Replit workspace will run your Worker in dev mode, making your project available on a Replit subdomain. After a period of inactivity, your Repl may go to sleep until the **Run** button is pressed or the [Repl receives HTTP traffic](https://docs.replit.com/hosting/deploying-http-servers). To prevent your Repl from sleeping, enable [Always On](https://docs.replit.com/power-ups/always-on) in your Replit workspace settings.
+
+### Develop with persistent data
+
+You can persist development data between sessions. To run your Worker with data persisted in the `data` folder of your Repl, run the following in the Shell tab of your Replit workspace:
+
+```shell
+npm run start-persist
+```
+
+The **Run** button can also be updated to always run your Worker in persistent mode:
+1. Open `package.json`.
+2. Update the `replit-run-command` key with a value of `npm run start-persist`.
+
+## Deploy Worker to Cloudflare
+
+To deploy your Worker to the Cloudflare network, you must add your Cloudflare API token and Cloudflare account ID to Replit secrets.
+
+### 1. Add your Cloudflare API token to Replit secrets
+
+To add your Cloudflare API token to Replit secrets:
+
+1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com/).
+2. In **Account Home**, select  **My Profile** on the top right.
+3. Select **API Tokens** on the left-hand navigation.
+4. Select **Create Token**.
+5. Go to **Edit Cloudflare Workers** under **API Token Templates** and select **Use Template**.
+6. Under **Account Resources**, select *All accounts* (or a specific account).
+7. Under **Zone Resources**, change *Specific zone* to *All zones*.
+8. Select **Continue to summary**.
+9. Select **Create Token**.
+10. This gives you the API token needed. Copy it to [Replit secrets](https://docs.replit.com/programming-ide/storing-sensitive-information-environment-variables) with the name `CLOUDFLARE_API_TOKEN`.
+
+### 2. Add your Cloudflare Account ID to Replit secrets
+
+To add your Cloudflare account ID to Replit secrets:
+
+1. Log in to the Cloudflare dashboard > [**Workers**](https://dash.cloudflare.com/?to=/:account/workers/overview).
+2. In **Workers**, find your **Account ID** on the right side of the screen.
+3. Select **Click to copy** to copy your Account ID.
+4. Add this to [Replit secrets](https://docs.replit.com/programming-ide/storing-sensitive-information-environment-variables) with the name `CLOUDFLARE_ACCOUNT_ID`.
+
+Note: You may have to close and re-open the Shell tab of your Replit workspace before these secrets are available for use.
+
+### Publish Worker to Cloudflare
+
+After adding credentials to Replit secrets, you can publish your Worker to the Cloudflare global network. Your  Worker will publish to a `*.workers.dev` subdomain by default. To set up a `*.workers.dev` subdomain, go to the Cloudflare dashboard > [**Workers**](https://dash.cloudflare.com/?to=/:account/workers/overview) > Your subdomain > Change. To publish your project, run:
+
+```shell
+npm run deploy
+```
+
+After you have deployed your Worker, you can set up a custom domain for your project in the Cloudflare dashboard. To set up a custom domain, go to [**Workers**](https://dash.cloudflare.com/?to=/:account/workers/overview) in the Cloudflare dashboard > select your Worker > **Triggers** > **Add Custom Domain**.
+
+To configure the **Run** button to publish to the Cloudflare global network rather than a Replit subdomain: 
+1. Open `package.json`.
+2. Update the `replit-run-command` key with a value of `npm run deploy`.
+
+## Discord
+
+Join the Cloudflare Developers community Discord to ask questions, show off what you are building, and discuss the platform with other developers: [discord.gg/cloudflaredev](https://discord.gg/cloudflaredev).