@bsb/observable-zipkin 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# BSB Observable Zipkin
+
+Zipkin tracing integration for the Better Service Base (BSB) framework.
+
+## Features
+
+- Direct Zipkin v2 API integration
+- Distributed tracing with OpenTelemetry instrumentation
+- Configurable sampling rates
+- Batch span export with configurable flush intervals
+- Console logging fallback for non-trace observability
+- Full TypeScript support
+
+## Installation
+
+```bash
+npm install @bsb/observable-zipkin
+```
+
+## Configuration
+
+Add to your BSB configuration file:
+
+```yaml
+plugins:
+  observable:
+    - observable-zipkin
+
+observable-zipkin:
+  serviceName: my-service
+  serviceVersion: 1.0.0
+
+  zipkin:
+    url: http://localhost:9411/api/v2/spans
+    # Optional custom headers for authentication
+    # headers:
+    #   Authorization: Bearer token123
+
+  export:
+    maxBatchSize: 100
+    maxQueueSize: 2048
+    scheduledDelayMillis: 5000
+
+  samplingRate: 1.0  # 1.0 = 100%, 0.5 = 50%
+
+  # Console logging (Zipkin doesn't handle logs/metrics)
+  console:
+    enabled: true
+    logLevel: info  # debug | info | warn | error
+
+  # Optional resource attributes
+  resourceAttributes:
+    environment: production
+    region: us-east-1
+```
+
+## What Gets Exported
+
+### Traces (to Zipkin)
+- All span lifecycle events (start, end, error)
+- Span attributes and context
+- Distributed trace propagation
+- Exception tracking
+
+### Logs (to Console)
+- Debug, info, warn, error levels
+- Structured logging with trace context
+- Configurable log level filtering
+
+### Metrics (No-op)
+- Zipkin is trace-only, no metrics support
+- Use `observable-opentelemetry` or `observable-prometheus` for metrics
+
+## Usage
+
+The plugin automatically integrates with BSB's Observable pattern:
+
+```typescript
+export class MyService extends BSBService<InstanceType<typeof Config>, typeof EventSchemas> {
+  static Config = Config;
+  static EventSchemas = EventSchemas;
+
+  public async run(obs: Observable) {
+    // Traces automatically sent to Zipkin
+    obs.log.info("Service started");  // Console log
+
+    // Create child span
+    const workObs = obs.span("heavy-work");
+    workObs.setAttribute("work.type", "batch");
+
+    try {
+      await this.doWork();
+      workObs.end();
+    } catch (error) {
+      workObs.recordException(error);
+      workObs.end();
+    }
+  }
+}
+```
+
+## Zipkin Setup
+
+Run Zipkin locally with Docker:
+
+```bash
+docker run -d -p 9411:9411 openzipkin/zipkin
+```
+
+Access UI at: http://localhost:9411
+
+## Architecture
+
+```
+BSB Application
+    ↓
+Observable (DTrace)
+    ↓
+observable-zipkin
+    ↓
+OpenTelemetry SDK
+    ↓
+Zipkin Exporter
+    ↓
+Zipkin Server (HTTP)
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `serviceName` | string | `"bsb-service"` | Service identifier in Zipkin |
+| `serviceVersion` | string | - | Service version tag |
+| `zipkin.url` | string | `"http://localhost:9411/api/v2/spans"` | Zipkin API endpoint |
+| `zipkin.headers` | object | - | Custom HTTP headers |
+| `export.maxBatchSize` | number | `100` | Max spans per batch |
+| `export.maxQueueSize` | number | `2048` | Max queued spans |
+| `export.scheduledDelayMillis` | number | `5000` | Flush interval (ms) |
+| `samplingRate` | number | `1.0` | Sampling probability (0-1) |
+| `console.enabled` | boolean | `true` | Enable console logs |
+| `console.logLevel` | string | `"info"` | Minimum log level |
+
+## Comparison with Other Observability Plugins
+
+| Plugin | Traces | Metrics | Logs | Backend |
+|--------|--------|---------|------|---------|
+| observable-zipkin | ✅ | ❌ | Console | Zipkin |
+| observable-opentelemetry | ✅ | ✅ | ✅ | OTLP Collector |
+| observable-default | ❌ | ❌ | Console | - |
+
+## License
+
+AGPL-3.0 - See LICENSE file for details.
+
+Commercial licenses available at https://www.bettercorp.dev

package/bsb-plugin.json

@@ -0,0 +1,18 @@
+{
+  "nodejs": [
+    {
+      "id": "observable-zipkin",
+      "name": "observable-zipkin",
+      "basePath": "./",
+      "description": "Zipkin tracing integration for BSB framework",
+      "tags": [
+        "zipkin",
+        "tracing",
+        "observability",
+        "distributed-tracing"
+      ],
+      "documentation": [],
+      "pluginPath": "src/plugins/observable-zipkin/"
+    }
+  ]
+}

package/lib/plugins/observable-zipkin/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { BSBObservable, BSBObservableConstructor, BSBError } from "@bsb/base";
+import { DTrace, LogMeta } from "@bsb/base";
+import { z } from "zod";
+export declare const Config: import("@bsb/base").BSBPluginConfigClass<z.ZodObject<{
+    serviceName: z.ZodDefault<z.ZodString>;
+    serviceVersion: z.ZodOptional<z.ZodString>;
+    zipkin: z.ZodObject<{
+        url: z.ZodDefault<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        statusCodeTagName: z.ZodDefault<z.ZodString>;
+        statusDescriptionTagName: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    export: z.ZodObject<{
+        maxBatchSize: z.ZodDefault<z.ZodNumber>;
+        maxQueueSize: z.ZodDefault<z.ZodNumber>;
+        scheduledDelayMillis: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    resourceAttributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    samplingRate: z.ZodDefault<z.ZodNumber>;
+    console: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        logLevel: z.ZodDefault<z.ZodEnum<{
+            error: "error";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>>;
+/**
+ * Zipkin observable plugin for distributed tracing
+ *
+ * Exports traces directly to Zipkin using the Zipkin v2 API format.
+ * Provides console logging fallback for non-trace observability.
+ */
+export declare class Plugin extends BSBObservable<InstanceType<typeof Config>> {
+    static Config: import("@bsb/base").BSBPluginConfigClass<z.ZodObject<{
+        serviceName: z.ZodDefault<z.ZodString>;
+        serviceVersion: z.ZodOptional<z.ZodString>;
+        zipkin: z.ZodObject<{
+            url: z.ZodDefault<z.ZodString>;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            statusCodeTagName: z.ZodDefault<z.ZodString>;
+            statusDescriptionTagName: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>;
+        export: z.ZodObject<{
+            maxBatchSize: z.ZodDefault<z.ZodNumber>;
+            maxQueueSize: z.ZodDefault<z.ZodNumber>;
+            scheduledDelayMillis: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>;
+        resourceAttributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        samplingRate: z.ZodDefault<z.ZodNumber>;
+        console: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            logLevel: z.ZodDefault<z.ZodEnum<{
+                error: "error";
+                debug: "debug";
+                info: "info";
+                warn: "warn";
+            }>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    private logFormatter;
+    private tracerProvider;
+    private tracer;
+    private exporter;
+    private isDisposed;
+    private spans;
+    constructor(config: BSBObservableConstructor<InstanceType<typeof Config>>);
+    init(): Promise<void>;
+    run(): Promise<void>;
+    /**
+     * Convert BSB DTrace to OpenTelemetry trace context
+     */
+    private getTraceContext;
+    /**
+     * Console logging fallback (Zipkin doesn't handle logs)
+     */
+    private writeConsoleLog;
+    debug(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    info(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    warn(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void;
+    error(trace: DTrace, pluginName: string, message: string | BSBError<any>, meta?: LogMeta<any>): void;
+    createCounter(): void;
+    incrementCounter(): void;
+    createGauge(): void;
+    setGauge(): void;
+    createHistogram(): void;
+    observeHistogram(): void;
+    spanStart(trace: DTrace, pluginName: string, spanName: string, parentSpanId: string | null, attributes?: Record<string, string | number | boolean>): void;
+    spanEnd(trace: DTrace, pluginName: string, attributes?: Record<string, string | number | boolean>): void;
+    spanError(trace: DTrace, pluginName: string, error: Error, attributes?: Record<string, string | number | boolean>): void;
+    dispose(): Promise<void>;
+}

package/lib/plugins/observable-zipkin/index.js

@@ -0,0 +1,296 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Plugin = exports.Config = void 0;
+const base_1 = require("@bsb/base");
+const zod_1 = require("zod");
+const api = __importStar(require("@opentelemetry/api"));
+const resources_1 = require("@opentelemetry/resources");
+const semantic_conventions_1 = require("@opentelemetry/semantic-conventions");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const exporter_zipkin_1 = require("@opentelemetry/exporter-zipkin");
+const ConfigSchema = zod_1.z.object({
+    serviceName: zod_1.z.string().default("bsb-service"),
+    serviceVersion: zod_1.z.string().optional(),
+    zipkin: zod_1.z.object({
+        url: zod_1.z.string().url().default("http://localhost:9411/api/v2/spans"),
+        headers: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+        statusCodeTagName: zod_1.z.string().default("http.status_code"),
+        statusDescriptionTagName: zod_1.z.string().default("http.status_text"),
+    }),
+    export: zod_1.z.object({
+        maxBatchSize: zod_1.z.number().int().min(1).default(100),
+        maxQueueSize: zod_1.z.number().int().min(1).default(2048),
+        scheduledDelayMillis: zod_1.z.number().int().min(100).default(5000),
+    }),
+    resourceAttributes: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).default({}),
+    samplingRate: zod_1.z.number().min(0).max(1).default(1.0),
+    console: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(true),
+        logLevel: zod_1.z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+    }),
+});
+exports.Config = (0, base_1.createConfigSchema)({
+    name: 'observable-zipkin',
+    description: 'Zipkin tracing integration for BSB framework',
+    version: '1.0.0',
+    tags: ['zipkin', 'tracing', 'observability', 'distributed-tracing'],
+}, ConfigSchema);
+/**
+ * Zipkin observable plugin for distributed tracing
+ *
+ * Exports traces directly to Zipkin using the Zipkin v2 API format.
+ * Provides console logging fallback for non-trace observability.
+ */
+class Plugin extends base_1.BSBObservable {
+    constructor(config) {
+        super(config);
+        this.logFormatter = new base_1.LogFormatter();
+        this.tracerProvider = null;
+        this.tracer = null;
+        this.exporter = null;
+        this.isDisposed = false;
+        this.spans = new Map();
+    }
+    async init() {
+        const resource = new resources_1.Resource({
+            [semantic_conventions_1.ATTR_SERVICE_NAME]: this.config.serviceName,
+            ...(this.config.serviceVersion && { [semantic_conventions_1.ATTR_SERVICE_VERSION]: this.config.serviceVersion }),
+            ...this.config.resourceAttributes,
+        });
+        this.exporter = new exporter_zipkin_1.ZipkinExporter({
+            url: this.config.zipkin.url,
+            headers: this.config.zipkin.headers,
+            statusCodeTagName: this.config.zipkin.statusCodeTagName,
+            statusDescriptionTagName: this.config.zipkin.statusDescriptionTagName,
+        });
+        this.tracerProvider = new sdk_trace_base_1.BasicTracerProvider({
+            resource,
+        });
+        this.tracerProvider.addSpanProcessor(new sdk_trace_base_1.BatchSpanProcessor(this.exporter, {
+            maxQueueSize: this.config.export.maxQueueSize,
+            maxExportBatchSize: this.config.export.maxBatchSize,
+            scheduledDelayMillis: this.config.export.scheduledDelayMillis,
+        }));
+        this.tracerProvider.register();
+        this.tracer = this.tracerProvider.getTracer(this.config.serviceName, this.config.serviceVersion);
+    }
+    async run() {
+        // No runtime setup needed
+    }
+    /**
+     * Convert BSB DTrace to OpenTelemetry trace context
+     */
+    getTraceContext(trace) {
+        const traceId = trace.t.padStart(32, "0").substring(0, 32);
+        const spanId = trace.s.padStart(16, "0").substring(0, 16);
+        const spanContext = {
+            traceId,
+            spanId,
+            traceFlags: api.TraceFlags.SAMPLED,
+        };
+        return api.trace.setSpanContext(api.context.active(), spanContext);
+    }
+    /**
+     * Console logging fallback (Zipkin doesn't handle logs)
+     */
+    writeConsoleLog(level, trace, pluginName, message, meta) {
+        if (!this.config.console.enabled) {
+            return;
+        }
+        const formattedMessage = this.logFormatter.formatLog(trace, message, meta);
+        const timestamp = new Date().toISOString();
+        const logLine = `${timestamp} [${level.toUpperCase()}] [${pluginName}] ${formattedMessage}`;
+        const levelMap = {
+            debug: 0,
+            info: 1,
+            warn: 2,
+            error: 3,
+        };
+        const currentLevel = levelMap[this.config.console.logLevel] ?? 1;
+        const messageLevel = levelMap[level.toLowerCase()] ?? 1;
+        if (messageLevel < currentLevel) {
+            return;
+        }
+        let func = console.log;
+        switch (level.toLowerCase()) {
+            case 'debug':
+                func = console.debug;
+                break;
+            case 'info':
+                func = console.log;
+                break;
+            case 'warn':
+                func = console.warn;
+                break;
+            case 'error':
+                func = console.error;
+                break;
+        }
+        func(logLine);
+    }
+    // Logging methods (fallback to console - Zipkin is trace-only)
+    debug(trace, pluginName, message, meta) {
+        if (this.mode === "production") {
+            return;
+        }
+        this.writeConsoleLog("debug", trace, pluginName, message, meta);
+    }
+    info(trace, pluginName, message, meta) {
+        this.writeConsoleLog("info", trace, pluginName, message, meta);
+    }
+    warn(trace, pluginName, message, meta) {
+        this.writeConsoleLog("warn", trace, pluginName, message, meta);
+    }
+    error(trace, pluginName, message, meta) {
+        if (message instanceof base_1.BSBError) {
+            if (message.raw !== null) {
+                this.writeConsoleLog("error", message.raw.trace, pluginName, message.raw.message, message.raw.meta);
+            }
+            else {
+                this.writeConsoleLog("error", trace, pluginName, message.message);
+            }
+        }
+        else {
+            this.writeConsoleLog("error", trace, pluginName, message, meta);
+        }
+    }
+    // Metrics methods (no-op - Zipkin is trace-only)
+    createCounter() {
+        // Zipkin doesn't support metrics
+    }
+    incrementCounter() {
+        // Zipkin doesn't support metrics
+    }
+    createGauge() {
+        // Zipkin doesn't support metrics
+    }
+    setGauge() {
+        // Zipkin doesn't support metrics
+    }
+    createHistogram() {
+        // Zipkin doesn't support metrics
+    }
+    observeHistogram() {
+        // Zipkin doesn't support metrics
+    }
+    // Tracing methods
+    spanStart(trace, pluginName, spanName, parentSpanId, attributes) {
+        if (!this.tracer || this.isDisposed) {
+            return;
+        }
+        const context = this.getTraceContext(trace);
+        const span = this.tracer.startSpan(spanName, {
+            attributes: {
+                "bsb.plugin": pluginName,
+                "bsb.trace.t": trace.t,
+                "bsb.trace.s": trace.s,
+                ...(parentSpanId ? { "bsb.parent_span_id": parentSpanId } : {}),
+                ...attributes,
+            },
+        }, context);
+        const spanKey = `${trace.t}:${trace.s}`;
+        this.spans.set(spanKey, span);
+    }
+    spanEnd(trace, pluginName, attributes) {
+        if (this.isDisposed) {
+            return;
+        }
+        const spanKey = `${trace.t}:${trace.s}`;
+        const span = this.spans.get(spanKey);
+        if (span) {
+            if (attributes) {
+                span.setAttributes(attributes);
+            }
+            span.end();
+            this.spans.delete(spanKey);
+        }
+    }
+    spanError(trace, pluginName, error, attributes) {
+        if (this.isDisposed) {
+            return;
+        }
+        const spanKey = `${trace.t}:${trace.s}`;
+        const span = this.spans.get(spanKey);
+        if (span) {
+            span.recordException(error);
+            span.setStatus({ code: api.SpanStatusCode.ERROR, message: error.message });
+            if (attributes) {
+                span.setAttributes(attributes);
+            }
+        }
+    }
+    async dispose() {
+        this.isDisposed = true;
+        for (const span of this.spans.values()) {
+            span.end();
+        }
+        this.spans.clear();
+        if (this.tracerProvider) {
+            await this.tracerProvider.shutdown();
+            this.tracerProvider = null;
+        }
+        this.tracer = null;
+        this.exporter = null;
+    }
+}
+exports.Plugin = Plugin;
+Plugin.Config = exports.Config;

package/lib/schemas/observable-zipkin.json

@@ -0,0 +1,151 @@
+{
+  "pluginName": "observable-zipkin",
+  "version": "1.0.0",
+  "events": {},
+  "configSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "serviceName": {
+        "default": "bsb-service",
+        "type": "string"
+      },
+      "serviceVersion": {
+        "type": "string"
+      },
+      "zipkin": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "default": "http://localhost:9411/api/v2/spans",
+            "type": "string",
+            "format": "uri"
+          },
+          "headers": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "statusCodeTagName": {
+            "default": "http.status_code",
+            "type": "string"
+          },
+          "statusDescriptionTagName": {
+            "default": "http.status_text",
+            "type": "string"
+          }
+        },
+        "required": [
+          "url",
+          "statusCodeTagName",
+          "statusDescriptionTagName"
+        ],
+        "additionalProperties": false
+      },
+      "export": {
+        "type": "object",
+        "properties": {
+          "maxBatchSize": {
+            "default": 100,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "maxQueueSize": {
+            "default": 2048,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "scheduledDelayMillis": {
+            "default": 5000,
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 9007199254740991
+          }
+        },
+        "required": [
+          "maxBatchSize",
+          "maxQueueSize",
+          "scheduledDelayMillis"
+        ],
+        "additionalProperties": false
+      },
+      "resourceAttributes": {
+        "default": {},
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "samplingRate": {
+        "default": 1,
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "console": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "default": true,
+            "type": "boolean"
+          },
+          "logLevel": {
+            "default": "info",
+            "type": "string",
+            "enum": [
+              "debug",
+              "info",
+              "warn",
+              "error"
+            ]
+          }
+        },
+        "required": [
+          "enabled",
+          "logLevel"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "required": [
+      "serviceName",
+      "zipkin",
+      "export",
+      "resourceAttributes",
+      "samplingRate",
+      "console"
+    ],
+    "additionalProperties": false
+  },
+  "pluginType": "observable",
+  "capabilities": {
+    "logging": {
+      "debug": true,
+      "info": true,
+      "warn": true,
+      "error": true
+    },
+    "metrics": {
+      "createCounter": true,
+      "createGauge": true,
+      "createHistogram": true,
+      "incrementCounter": true,
+      "setGauge": true,
+      "observeHistogram": true
+    },
+    "tracing": {
+      "spanStart": true,
+      "spanEnd": true,
+      "spanError": true
+    }
+  }
+}

package/lib/schemas/observable-zipkin.plugin.json

@@ -0,0 +1,139 @@
+{
+  "id": "observable-zipkin",
+  "name": "observable-zipkin",
+  "version": "1.0.0",
+  "description": "Zipkin tracing integration for BSB framework",
+  "category": "observable",
+  "tags": [
+    "zipkin",
+    "tracing",
+    "observability",
+    "distributed-tracing"
+  ],
+  "documentation": [],
+  "dependencies": [],
+  "configSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "serviceName": {
+        "default": "bsb-service",
+        "type": "string"
+      },
+      "serviceVersion": {
+        "type": "string"
+      },
+      "zipkin": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "default": "http://localhost:9411/api/v2/spans",
+            "type": "string",
+            "format": "uri"
+          },
+          "headers": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "statusCodeTagName": {
+            "default": "http.status_code",
+            "type": "string"
+          },
+          "statusDescriptionTagName": {
+            "default": "http.status_text",
+            "type": "string"
+          }
+        },
+        "required": [
+          "url",
+          "statusCodeTagName",
+          "statusDescriptionTagName"
+        ],
+        "additionalProperties": false
+      },
+      "export": {
+        "type": "object",
+        "properties": {
+          "maxBatchSize": {
+            "default": 100,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "maxQueueSize": {
+            "default": 2048,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "scheduledDelayMillis": {
+            "default": 5000,
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 9007199254740991
+          }
+        },
+        "required": [
+          "maxBatchSize",
+          "maxQueueSize",
+          "scheduledDelayMillis"
+        ],
+        "additionalProperties": false
+      },
+      "resourceAttributes": {
+        "default": {},
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "samplingRate": {
+        "default": 1,
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
+      "console": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "default": true,
+            "type": "boolean"
+          },
+          "logLevel": {
+            "default": "info",
+            "type": "string",
+            "enum": [
+              "debug",
+              "info",
+              "warn",
+              "error"
+            ]
+          }
+        },
+        "required": [
+          "enabled",
+          "logLevel"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "required": [
+      "serviceName",
+      "zipkin",
+      "export",
+      "resourceAttributes",
+      "samplingRate",
+      "console"
+    ],
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@bsb/observable-zipkin",
+  "version": "1.0.0",
+  "description": "Zipkin tracing integration for BSB framework",
+  "main": "lib/plugins/observable-zipkin/index.js",
+  "types": "lib/plugins/observable-zipkin/index.d.ts",
+  "scripts": {
+    "clean": "bsb-plugin-cli clean",
+    "build": "bsb-plugin-cli build",
+    "start": "bsb-plugin-cli start",
+    "dev": "bsb-plugin-cli dev",
+    "test": "bsb-plugin-cli test",
+    "publish:client": "bsb client publish",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "bsb",
+    "zipkin",
+    "tracing",
+    "observability",
+    "distributed-tracing",
+    "opentelemetry"
+  ],
+  "license": "(AGPL-3.0-only OR Commercial)",
+  "author": {
+    "name": "BetterCorp (PTY) Ltd",
+    "email": "nick@bettercorp.dev",
+    "url": "https://bettercorp.dev/"
+  },
+  "peerDependencies": {
+    "@bsb/base": "^9.0.0"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-zipkin": "^1.28.0",
+    "@opentelemetry/resources": "^1.28.0",
+    "@opentelemetry/sdk-trace-base": "^1.28.0",
+    "@opentelemetry/semantic-conventions": "^1.28.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@bsb/base": "file:../../../nodejs",
+    "@types/node": "^22.10.5",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.7.3"
+  },
+  "homepage": "https://io.bsbcode.dev/plugins/bsb/observable-zipkin"
+}
+

package/src/plugins/observable-zipkin/index.ts

@@ -0,0 +1,348 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import {
+  BSBObservable,
+  BSBObservableConstructor,
+  createConfigSchema,
+  LogFormatter,
+  BSBError
+} from "@bsb/base";
+import { DTrace, LogMeta } from "@bsb/base";
+import { z } from "zod";
+import * as api from "@opentelemetry/api";
+import { Resource } from "@opentelemetry/resources";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from "@opentelemetry/semantic-conventions";
+import { BasicTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { ZipkinExporter } from "@opentelemetry/exporter-zipkin";
+
+const ConfigSchema = z.object({
+    serviceName: z.string().default("bsb-service"),
+    serviceVersion: z.string().optional(),
+
+    zipkin: z.object({
+      url: z.string().url().default("http://localhost:9411/api/v2/spans"),
+      headers: z.record(z.string(), z.string()).optional(),
+      statusCodeTagName: z.string().default("http.status_code"),
+      statusDescriptionTagName: z.string().default("http.status_text"),
+    }),
+
+    export: z.object({
+      maxBatchSize: z.number().int().min(1).default(100),
+      maxQueueSize: z.number().int().min(1).default(2048),
+      scheduledDelayMillis: z.number().int().min(100).default(5000),
+    }),
+
+    resourceAttributes: z.record(z.string(), z.string()).default({}),
+    samplingRate: z.number().min(0).max(1).default(1.0),
+
+    console: z.object({
+      enabled: z.boolean().default(true),
+      logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+    }),
+  });
+
+export const Config = createConfigSchema(
+  {
+    name: 'observable-zipkin',
+    description: 'Zipkin tracing integration for BSB framework',
+    version: '1.0.0',
+    tags: ['zipkin', 'tracing', 'observability', 'distributed-tracing'],
+  },
+  ConfigSchema
+);
+
+/**
+ * Zipkin observable plugin for distributed tracing
+ *
+ * Exports traces directly to Zipkin using the Zipkin v2 API format.
+ * Provides console logging fallback for non-trace observability.
+ */
+export class Plugin extends BSBObservable<InstanceType<typeof Config>> {
+  static Config = Config;
+
+  private logFormatter = new LogFormatter();
+  private tracerProvider: BasicTracerProvider | null = null;
+  private tracer: api.Tracer | null = null;
+  private exporter: ZipkinExporter | null = null;
+  private isDisposed = false;
+
+  private spans = new Map<string, api.Span>();
+
+  constructor(config: BSBObservableConstructor<InstanceType<typeof Config>>) {
+    super(config);
+  }
+
+  public async init(): Promise<void> {
+    const resource = new Resource({
+      [ATTR_SERVICE_NAME]: this.config.serviceName,
+      ...(this.config.serviceVersion && { [ATTR_SERVICE_VERSION]: this.config.serviceVersion }),
+      ...this.config.resourceAttributes,
+    });
+
+    this.exporter = new ZipkinExporter({
+      url: this.config.zipkin.url,
+      headers: this.config.zipkin.headers,
+      statusCodeTagName: this.config.zipkin.statusCodeTagName,
+      statusDescriptionTagName: this.config.zipkin.statusDescriptionTagName,
+    });
+
+    this.tracerProvider = new BasicTracerProvider({
+      resource,
+    });
+
+    this.tracerProvider.addSpanProcessor(
+      new BatchSpanProcessor(this.exporter, {
+        maxQueueSize: this.config.export.maxQueueSize,
+        maxExportBatchSize: this.config.export.maxBatchSize,
+        scheduledDelayMillis: this.config.export.scheduledDelayMillis,
+      })
+    );
+
+    this.tracerProvider.register();
+
+    this.tracer = this.tracerProvider.getTracer(
+      this.config.serviceName,
+      this.config.serviceVersion
+    );
+  }
+
+  public async run(): Promise<void> {
+    // No runtime setup needed
+  }
+
+  /**
+   * Convert BSB DTrace to OpenTelemetry trace context
+   */
+  private getTraceContext(trace: DTrace): api.Context {
+    const traceId = trace.t.padStart(32, "0").substring(0, 32);
+    const spanId = trace.s.padStart(16, "0").substring(0, 16);
+
+    const spanContext: api.SpanContext = {
+      traceId,
+      spanId,
+      traceFlags: api.TraceFlags.SAMPLED,
+    };
+
+    return api.trace.setSpanContext(api.context.active(), spanContext);
+  }
+
+  /**
+   * Console logging fallback (Zipkin doesn't handle logs)
+   */
+  private writeConsoleLog(
+    level: string,
+    trace: DTrace,
+    pluginName: string,
+    message: string,
+    meta?: LogMeta<any>
+  ): void {
+    if (!this.config.console.enabled) {
+      return;
+    }
+
+    const formattedMessage = this.logFormatter.formatLog(trace, message, meta);
+    const timestamp = new Date().toISOString();
+    const logLine = `${timestamp} [${level.toUpperCase()}] [${pluginName}] ${formattedMessage}`;
+
+    const levelMap = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3,
+    } as const;
+
+    const currentLevel = levelMap[this.config.console.logLevel as keyof typeof levelMap] ?? 1;
+    const messageLevel = levelMap[level.toLowerCase() as keyof typeof levelMap] ?? 1;
+
+    if (messageLevel < currentLevel) {
+      return;
+    }
+
+    type ConsoleMethod = typeof console.debug | typeof console.log | typeof console.warn | typeof console.error;
+    let func: ConsoleMethod = console.log;
+
+    switch (level.toLowerCase()) {
+      case 'debug':
+        func = console.debug;
+        break;
+      case 'info':
+        func = console.log;
+        break;
+      case 'warn':
+        func = console.warn;
+        break;
+      case 'error':
+        func = console.error;
+        break;
+    }
+
+    func(logLine);
+  }
+
+  // Logging methods (fallback to console - Zipkin is trace-only)
+  public debug(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void {
+    if (this.mode === "production") {
+      return;
+    }
+    this.writeConsoleLog("debug", trace, pluginName, message, meta);
+  }
+
+  public info(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void {
+    this.writeConsoleLog("info", trace, pluginName, message, meta);
+  }
+
+  public warn(trace: DTrace, pluginName: string, message: string, meta: LogMeta<any>): void {
+    this.writeConsoleLog("warn", trace, pluginName, message, meta);
+  }
+
+  public error(trace: DTrace, pluginName: string, message: string | BSBError<any>, meta?: LogMeta<any>): void {
+    if (message instanceof BSBError) {
+      if (message.raw !== null) {
+        this.writeConsoleLog("error", message.raw.trace, pluginName, message.raw.message, message.raw.meta);
+      } else {
+        this.writeConsoleLog("error", trace, pluginName, message.message);
+      }
+    } else {
+      this.writeConsoleLog("error", trace, pluginName, message, meta);
+    }
+  }
+
+  // Metrics methods (no-op - Zipkin is trace-only)
+  public createCounter(): void {
+    // Zipkin doesn't support metrics
+  }
+
+  public incrementCounter(): void {
+    // Zipkin doesn't support metrics
+  }
+
+  public createGauge(): void {
+    // Zipkin doesn't support metrics
+  }
+
+  public setGauge(): void {
+    // Zipkin doesn't support metrics
+  }
+
+  public createHistogram(): void {
+    // Zipkin doesn't support metrics
+  }
+
+  public observeHistogram(): void {
+    // Zipkin doesn't support metrics
+  }
+
+  // Tracing methods
+  public spanStart(
+    trace: DTrace,
+    pluginName: string,
+    spanName: string,
+    parentSpanId: string | null,
+    attributes?: Record<string, string | number | boolean>
+  ): void {
+    if (!this.tracer || this.isDisposed) {
+      return;
+    }
+
+    const context = this.getTraceContext(trace);
+    const span = this.tracer.startSpan(
+      spanName,
+      {
+        attributes: {
+          "bsb.plugin": pluginName,
+          "bsb.trace.t": trace.t,
+          "bsb.trace.s": trace.s,
+          ...(parentSpanId ? { "bsb.parent_span_id": parentSpanId } : {}),
+          ...attributes,
+        },
+      },
+      context
+    );
+
+    const spanKey = `${trace.t}:${trace.s}`;
+    this.spans.set(spanKey, span);
+  }
+
+  public spanEnd(
+    trace: DTrace,
+    pluginName: string,
+    attributes?: Record<string, string | number | boolean>
+  ): void {
+    if (this.isDisposed) {
+      return;
+    }
+
+    const spanKey = `${trace.t}:${trace.s}`;
+    const span = this.spans.get(spanKey);
+    if (span) {
+      if (attributes) {
+        span.setAttributes(attributes);
+      }
+      span.end();
+      this.spans.delete(spanKey);
+    }
+  }
+
+  public spanError(
+    trace: DTrace,
+    pluginName: string,
+    error: Error,
+    attributes?: Record<string, string | number | boolean>
+  ): void {
+    if (this.isDisposed) {
+      return;
+    }
+
+    const spanKey = `${trace.t}:${trace.s}`;
+    const span = this.spans.get(spanKey);
+    if (span) {
+      span.recordException(error);
+      span.setStatus({ code: api.SpanStatusCode.ERROR, message: error.message });
+      if (attributes) {
+        span.setAttributes(attributes);
+      }
+    }
+  }
+
+  public async dispose(): Promise<void> {
+    this.isDisposed = true;
+
+    for (const span of this.spans.values()) {
+      span.end();
+    }
+    this.spans.clear();
+
+    if (this.tracerProvider) {
+      await this.tracerProvider.shutdown();
+      this.tracerProvider = null;
+    }
+
+    this.tracer = null;
+    this.exporter = null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "./lib",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "lib"]
+}