@maestro-js/agent-skills 1.0.0-alpha.0

package/dist/maestro-packages/tracing.md

@@ -0,0 +1,240 @@
+---
+name: tracing
+description: "Distributed tracing package built on OpenTelemetry with pluggable providers (Sentry, Maestro). Use when working with @maestro-js/tracing. Key capabilities: wrap functions for automatic span tracking, create active spans with duration measurement, proxy entire objects for tracing, serialize/deserialize trace context across process boundaries (dehydrate/hydrate), add custom log transports for span events, integrate Sentry as a tracing provider."
+---
+
+# @maestro-js/tracing
+
+Distributed tracing built on OpenTelemetry. Tracks function calls, durations, and parent/child relationships across the request lifecycle with pluggable providers (Sentry or the built-in Maestro tracer).
+
+## Quick Setup
+
+```ts
+import { Tracing } from '@maestro-js/tracing'
+
+// Use the default Maestro tracer (works out of the box)
+const result = Tracing.startActiveSpan('my-operation', () => {
+  return doWork()
+})
+
+// Or set Sentry as the provider
+import * as Sentry from '@sentry/node'
+Tracing.setProvider(Tracing.providers.sentry(Sentry))
+```
+
+## Providers
+
+### Maestro (default)
+
+The `MaestroTracerProvider` is set as the global OpenTelemetry tracer provider automatically on import. It wraps every span to capture attributes, start/end times, and parent span IDs, then logs them through the built-in `Log` transport system.
+
+No configuration required -- it works immediately.
+
+### Sentry
+
+Pass a Sentry SDK instance to configure Sentry as the tracing backend. The factory sets up the `SentrySampler`, `SentrySpanProcessor`, `SentryPropagator`, and `SentryContextManager`.
+
+```ts
+import * as Sentry from '@sentry/node'
+import { Tracing } from '@maestro-js/tracing'
+
+Sentry.init({ dsn: '...', tracesSampleRate: 1.0 })
+Tracing.setProvider(Tracing.providers.sentry(Sentry))
+```
+
+The Sentry provider expects an object with:
+- `getClient()` -- returns the Sentry client
+- `SentryContextManager` -- the context manager constructor
+- `validateOpenTelemetrySetup()` -- validates the OTEL integration
+
+## API Reference
+
+### `Tracing.startActiveSpan(name, fn)`
+
+Start a span that becomes the active span for the duration of `fn`. Automatically ends the span when `fn` returns or when the returned Promise resolves/rejects.
+
+```ts
+// Simple string name
+Tracing.startActiveSpan('fetch-user', () => {
+  return db.query('SELECT * FROM users WHERE id = ?', [userId])
+})
+
+// With SpanOptions
+Tracing.startActiveSpan({ name: 'fetch-user', attributes: { userId } }, () => {
+  return db.query('SELECT * FROM users WHERE id = ?', [userId])
+})
+```
+
+### `Tracing.wrap(name, fn)`
+
+Return a new function that automatically creates a span on every invocation. The wrapped function preserves the original function's properties.
+
+```ts
+const tracedFetch = Tracing.wrap('fetch-data', fetchData)
+await tracedFetch(url) // each call creates a span
+```
+
+### `Tracing.isWrapped(fn)`
+
+Check whether a function has already been wrapped by the current tracer.
+
+```ts
+if (!Tracing.isWrapped(myFn)) {
+  myFn = Tracing.wrap('myFn', myFn)
+}
+```
+
+### `Tracing.proxy(obj, options?)`
+
+Wrap an entire object so every function call on it is traced. Nested objects are proxied recursively with dotted tracer names. Use `options.ignore` to skip specific properties.
+
+```ts
+const tracedService = Tracing.proxy(userService)
+await tracedService.findById(123) // creates span "findById"
+
+// Ignore specific methods
+const tracedService = Tracing.proxy(userService, {
+  ignore: ({ name }) => name === 'toString'
+})
+```
+
+The `ignore` option accepts a single predicate or an array of predicates with signature `(options: { name: string; tracer: string | null }) => boolean`.
+
+### `Tracing.getTracer(name)`
+
+Get a named tracer for a specific package or module. Returns an object with `wrap`, `proxy`, `startActiveSpan`, and `isWrapped` scoped to that tracer name.
+
+```ts
+const { wrap, startActiveSpan, proxy } = Tracing.getTracer('my-package')
+```
+
+The default export (`Tracing.wrap`, `Tracing.startActiveSpan`, etc.) uses the `'maestro'` tracer.
+
+### `Tracing.getActiveSpan()`
+
+Return the currently active OpenTelemetry span, or `undefined` if none.
+
+```ts
+const span = Tracing.getActiveSpan()
+span?.setAttribute('user.id', userId)
+```
+
+### `Tracing.addTransport(transport)`
+
+Add a log transport that receives a `TraceLogMessage` for every completed span.
+
+```ts
+Tracing.addTransport({
+  info(message: Tracing.LogMessage) {
+    console.log(`[${message.name}] ${message.endTime - message.startTime}ms`)
+  }
+})
+```
+
+`TraceLogMessage` shape:
+- `name` -- span name
+- `id` -- span ID
+- `parentId` -- parent span ID or `null`
+- `startTime` / `endTime` -- `performance.now()` timestamps
+- `instrumentation` -- instrumentation library name or `null`
+- `attributes` -- key-value span attributes
+
+### `Tracing.dehydrate()`
+
+Serialize the current trace context for transmission across process boundaries (e.g., into a queue job payload). Returns `null` if no active span.
+
+```ts
+const serialized = Tracing.dehydrate()
+// { traceId, spanId, traceFlags, traceState }
+```
+
+### `Tracing.hydrate(trace, callback)`
+
+Restore a serialized trace context and execute `callback` within it. The hydrated span is marked as remote, establishing the parent/child relationship across processes.
+
+```ts
+Tracing.hydrate(serializedTrace, () => {
+  // This runs within the original trace context
+  Tracing.startActiveSpan('process-job', () => {
+    return processJob(payload)
+  })
+})
+```
+
+### `Tracing.setProvider(provider)`
+
+Set the underlying OpenTelemetry `TracerProvider` delegate. The `MaestroTracerProvider` wraps this delegate to add logging and instrumentation.
+
+```ts
+Tracing.setProvider(Tracing.providers.sentry(Sentry))
+```
+
+## Common Patterns
+
+### Trace a queue job across processes
+
+```ts
+// Producer: serialize trace context into the job payload
+Tracing.startActiveSpan('enqueue-email', () => {
+  const trace = Tracing.dehydrate()
+  Queue.dispatch('send-email', { to, subject, body, trace })
+})
+
+// Consumer: restore trace context when processing the job
+function handleSendEmail(payload) {
+  Tracing.hydrate(payload.trace, () => {
+    Tracing.startActiveSpan('send-email', () => {
+      return mail.send(payload)
+    })
+  })
+}
+```
+
+### Trace an entire service object
+
+```ts
+const rawService = {
+  async getUser(id: number) { /* ... */ },
+  async updateUser(id: number, data: any) { /* ... */ },
+  helpers: {
+    formatName(user: any) { /* ... */ }
+  }
+}
+// All methods (including nested helpers.formatName) get spans
+const service = Tracing.proxy(rawService)
+```
+
+### Create a package-scoped tracer
+
+```ts
+const { wrap, startActiveSpan } = Tracing.getTracer('billing')
+
+export const createInvoice = wrap('createInvoice', async (order: Order) => {
+  return startActiveSpan('validate', () => validateOrder(order))
+})
+```
+
+## Cross-Package Integration
+
+- **@maestro-js/log** -- `MaestroTracerProvider` uses `Log.create()` internally; span completion events are emitted through the log transport system
+- **@maestro-js/context** -- spans preserve `AsyncLocalStorage` context; `Context.runWith` is used to restore the correct store when logging span events
+- **@maestro-js/queue** -- use `dehydrate`/`hydrate` to propagate trace context through queue job payloads
+
+## Types
+
+```ts
+declare namespace Tracing {
+  type Attributes = TracingAttributes
+  type LogMessage = TraceLogMessage
+  type Provider = api.TracerProvider
+  type DehydratedTrace = SerializedTrace
+}
+```
+
+## Package Info
+
+- **Package**: `@maestro-js/tracing`
+- **Dependencies**: `@opentelemetry/api`, `@opentelemetry/sdk-trace-node`, `@sentry/opentelemetry`, `@maestro-js/log`, `@maestro-js/context`
+- **No tests currently** (`echo 'No tests yet'`)
+- Build: `pnpm --filter @maestro-js/tracing build`
+- Typecheck: `pnpm --filter @maestro-js/tracing typecheck`

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@maestro-js/agent-skills",
+  "description": "Agent skills for the @maestro-js framework.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "generate-skills": "node scripts/generate-package-skills.ts",
+    "generate-choosing-npm-package-skill": "node scripts/generate-choosing-npm-package-skill.ts",
+    "generate-maestro-cli-skill": "node scripts/generate-maestro-cli-skill.ts",
+    "build": "node scripts/generate-package-skills.ts && node scripts/generate-choosing-npm-package-skill.ts && node scripts/generate-maestro-cli-skill.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}