@bsb/observable-axiom 1.0.0 → 1.0.1

package/README.md

@@ -1,15 +1,14 @@
-# BSB Observable Axiom
+# @bsb/observable-axiom
 
-Axiom.co integration for the Better Service Base (BSB) framework - unified observability for logs, metrics, and traces.
+Axiom.co observability integration for BSB. Exports logs, metrics, and traces to Axiom with OTLP tracing support.
 
-## Features
+## Key Features
 
-- **Unified Observability** - Logs, metrics, and traces in one platform
-- **Axiom SDK** - Official `@axiomhq/js` for logs and events
-- **OpenTelemetry Traces** - OTLP export to Axiom (native support)
-- **Structured Metrics** - Metrics as queryable events
-- **Batch Processing** - Efficient batching with configurable flush intervals
-- **Full TypeScript Support** - Type-safe configuration and no `any` types
+- Unified observability: logs, metrics, and traces
+- Axiom SDK for logs and events
+- OpenTelemetry tracing via OTLP
+- Batch processing with configurable flush interval
+- Resource attributes for consistent service metadata
 
 ## Installation
 
@@ -19,233 +18,85 @@ npm install @bsb/observable-axiom
 
 ## Configuration
 
-Add to your BSB configuration file:
+Add the plugin to your BSB configuration file:
 
 ```yaml
 plugins:
-  observable:
-    - observable-axiom
-
-observable-axiom:
-  serviceName: my-service
-  serviceVersion: 1.0.0
-
-  axiom:
-    token: ${AXIOM_TOKEN}           # Your Axiom API token
-    dataset: bsb-logs               # Axiom dataset name
-    orgId: ${AXIOM_ORG_ID}          # Optional: for Axiom Cloud
-    # url: https://axiom.mycompany.com  # Optional: for self-hosted
-
-  enabled:
-    logs: true
-    metrics: true
-    traces: true
-
-  export:
-    flushIntervalMs: 5000           # Flush every 5 seconds
-    maxBatchSize: 1000              # Max events per batch
-
-  # Optional resource attributes (added to all telemetry)
-  resourceAttributes:
-    environment: production
-    region: us-east-1
-    cluster: main
+  observables:
+    - plugin: "@bsb/observable-axiom"
+      enabled: true
+      config:
+        serviceName: "my-service"
+        serviceVersion: "1.0.0"
+        axiom:
+          token: "${AXIOM_TOKEN}"
+          dataset: "bsb-logs"
+          orgId: "${AXIOM_ORG_ID}"
+          # url: "https://axiom.mycompany.com" # Optional for self-hosted
+        enabled:
+          logs: true
+          metrics: true
+          traces: true
+        export:
+          flushIntervalMs: 5000
+          maxBatchSize: 1000
+        resourceAttributes:
+          environment: "production"
+          region: "us-east-1"
+          cluster: "main"
 ```
 
+### Configuration Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `serviceName` | Service identifier | `"bsb-service"` |
+| `serviceVersion` | Service version tag | - |
+| `axiom.token` | Axiom API token | Required |
+| `axiom.dataset` | Axiom dataset name | `"bsb-logs"` |
+| `axiom.orgId` | Organization ID (Axiom Cloud) | - |
+| `axiom.url` | Custom Axiom URL (self-hosted) | - |
+| `enabled.logs` | Enable log export | `true` |
+| `enabled.metrics` | Enable metric export | `true` |
+| `enabled.traces` | Enable trace export | `true` |
+| `export.flushIntervalMs` | Flush interval (ms) | `5000` |
+| `export.maxBatchSize` | Max events per batch | `1000` |
+| `resourceAttributes` | Custom attributes | `{}` |
+
 ## Environment Variables
 
 ```bash
-export AXIOM_TOKEN="xaat-your-token-here"
-export AXIOM_ORG_ID="your-org-id"  # Optional for cloud
-export AXIOM_DATASET="bsb-logs"
+AXIOM_TOKEN="xaat-your-token-here"
+AXIOM_ORG_ID="your-org-id"
+AXIOM_DATASET="bsb-logs"
 ```
 
-## What Gets Exported
-
-### Logs (to Axiom Dataset)
-- Structured JSON with trace context
-- Log levels: debug, info, warn, error
-- Plugin name and service metadata
-- Custom metadata from log calls
-- Resource attributes
-
-### Metrics (to Axiom Dataset as Events)
-- Counters, gauges, histograms
-- Stored as structured events
-- Queryable with Axiom Processing Language (APL)
-- Automatic timestamp and service tagging
-
-### Traces (to Axiom via OTLP)
-- Full distributed tracing
-- Span lifecycle (start, end, error)
-- Trace context propagation
-- Exception tracking
-
 ## Usage
 
-The plugin automatically integrates with BSB's Observable pattern:
+Once configured, logs, metrics, and traces are exported automatically:
 
 ```typescript
-export class MyService extends BSBService<InstanceType<typeof Config>, typeof EventSchemas> {
-  static Config = Config;
-  static EventSchemas = EventSchemas;
-
-  public async run(obs: Observable) {
-    // Logs automatically sent to Axiom
-    obs.log.info("Service started", { userId: 123 });
-
-    // Create child span (sent to Axiom traces)
-    const workObs = obs.span("process-request");
-    workObs.setAttribute("request.id", "req-123");
-
-    try {
-      await this.processRequest();
-      workObs.end();
-    } catch (error) {
-      workObs.recordException(error);
-      workObs.end();
-    }
-
-    // Metrics also sent to Axiom
-    // (BSB metrics API will emit these as events)
-  }
-}
-```
-
-## Axiom Setup
-
-### 1. Create Account
-Sign up at https://axiom.co
-
-### 2. Create Dataset
-```bash
-axiom dataset create bsb-logs
-```
-
-### 3. Create API Token
-```bash
-axiom token create bsb-ingest --scopes ingest --datasets bsb-logs
-```
-
-### 4. Configure BSB
-Add token to your configuration or environment variables.
-
-## Querying Data in Axiom
-
-### Logs Query (APL)
-```apl
-['bsb-logs']
-| where service == "my-service"
-| where level == "error"
-| order by _time desc
-| limit 100
+this.log.info("Service started", { userId: 123 });
+const workObs = this.obs.span("process-request");
+await this.events.emitEvent("user.created", { userId: "123" });
+workObs.end();
 ```
 
-### Metrics Query
-```apl
-['bsb-logs']
-| where metric_type == "counter"
-| where metric_name == "requests_total"
-| summarize sum(value) by bin(_time, 1m)
-```
+## Axiom Setup (Quick)
 
-### Trace Analysis
-Use Axiom's Trace view to explore distributed traces with automatic service maps and performance analytics.
+1. Create a dataset
+2. Create an ingest token with dataset access
+3. Set `AXIOM_TOKEN` and `AXIOM_DATASET` in the environment
 
-## Architecture
+## Documentation
 
-```
-BSB Application
-    ↓
-Observable (DTrace)
-    ↓
-observable-axiom
-    ├── Logs/Metrics → Axiom SDK → Axiom Dataset
-    └── Traces → OTLP Exporter → Axiom Traces
-```
+Detailed documentation (used by the BSB Registry): `https://github.com/BetterCorp/better-service-base/blob/master/plugins/nodejs/observable-axiom/docs/plugin.md`
 
-## Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `serviceName` | string | `"bsb-service"` | Service identifier |
-| `serviceVersion` | string | - | Service version tag |
-| `axiom.token` | string | **required** | Axiom API token |
-| `axiom.dataset` | string | `"bsb-logs"` | Dataset name |
-| `axiom.orgId` | string | - | Organization ID (cloud) |
-| `axiom.url` | string | - | Custom URL (self-hosted) |
-| `enabled.logs` | boolean | `true` | Enable log export |
-| `enabled.metrics` | boolean | `true` | Enable metrics export |
-| `enabled.traces` | boolean | `true` | Enable trace export |
-| `export.flushIntervalMs` | number | `5000` | Flush interval (ms) |
-| `export.maxBatchSize` | number | `1000` | Max events per batch |
-| `resourceAttributes` | object | `{}` | Custom attributes |
-
-## Comparison with Other Observability Plugins
-
-| Plugin | Logs | Metrics | Traces | Backend |
-|--------|------|---------|--------|---------|
-| observable-axiom | ✅ | ✅ | ✅ | Axiom.co |
-| observable-opentelemetry | ✅ | ✅ | ✅ | OTLP Collector |
-| observable-zipkin | Console | ❌ | ✅ | Zipkin |
-| observable-default | Console | ❌ | ❌ | - |
-
-## Best Practices
-
-### 1. Use Datasets Strategically
-```yaml
-# Production
-axiom:
-  dataset: prod-logs
+## Links
 
-# Development
-axiom:
-  dataset: dev-logs
-```
-
-### 2. Set Resource Attributes
-```yaml
-resourceAttributes:
-  environment: ${ENVIRONMENT}
-  deployment: ${DEPLOYMENT_ID}
-  datacenter: ${DATACENTER}
-```
-
-### 3. Control Batch Size
-```yaml
-export:
-  # High-volume services
-  flushIntervalMs: 1000
-  maxBatchSize: 5000
-
-  # Low-volume services
-  flushIntervalMs: 10000
-  maxBatchSize: 100
-```
-
-### 4. Use Structured Logging
-```typescript
-// Good - queryable fields
-obs.log.info("User logged in", {
-  userId: user.id,
-  email: user.email
-});
-
-// Bad - unstructured
-obs.log.info(`User ${user.email} logged in`);
-```
-
-## Axiom Features
-
-- **APL (Axiom Processing Language)** - Powerful query language
-- **Service Maps** - Automatic trace visualization
-- **Monitors & Alerts** - Real-time alerting on anomalies
-- **Dashboards** - Custom visualizations
-- **Notebooks** - Collaborative analysis
-- **Retention** - Configurable data retention policies
+- GitHub: `https://github.com/BetterCorp/better-service-base/tree/master/plugins/nodejs/observable-axiom`
+- BSB Registry (package): `https://io.bsbcode.dev/packages/nodejs/@bsb/observable-axiom`
 
 ## License
 
-AGPL-3.0 - See LICENSE file for details.
-
-Commercial licenses available at https://www.bettercorp.dev
+(AGPL-3.0-only OR Commercial)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsb/observable-axiom",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Axiom.co observability integration for BSB framework",
   "main": "lib/plugins/observable-axiom/index.js",
   "types": "lib/plugins/observable-axiom/index.d.ts",
@@ -26,7 +26,7 @@
   "license": "(AGPL-3.0-only OR Commercial)",
   "author": {
     "name": "BetterCorp (PTY) Ltd",
-    "email": "nick@bettercorp.dev",
+    "email": "ninja@bettercorp.dev",
     "url": "https://bettercorp.dev/"
   },
   "peerDependencies": {
@@ -49,6 +49,9 @@
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
   },
-  "homepage": "https://io.bsbcode.dev/plugins/bsb/observable-axiom"
+  "homepage": "https://io.bsbcode.dev/packages/nodejs/@bsb/observable-axiom"
 }
-
+
+
+
+