Narrative telemetry: structured events + config-driven stories
npm install @dropsilk/gossamerNarrative Telemetry: Structured events + Config-driven stories.
bash
npm install @dropsilk/gossamer
or
pnpm add @dropsilk/gossamer
`
Quick Start
$3
Create a gossamer.config.ts (or .js, .mjs) in your project root:
`typescript
import type { GossamerUserConfig } from "@dropsilk/gossamer";
const config: GossamerUserConfig = {
enabled: true,
verbosity: 0,
// Define log levels
levels: {
INFO: { active: true, label: "INFO", colour: "green" },
ERROR: { active: true, label: "ERROR", colour: "red" },
},
// Define known events
events: {
"user:login": { level: "INFO" },
"user:logout": { level: "INFO" },
"order:create": { level: "INFO" },
"order:complete": { level: "INFO" },
},
// Define Stories
stories: {
"UserSession": {
enabled: true,
correlationKey: "userId", // How to link events to this story
trigger: "user:login", // Event that starts the story
ender: "user:logout", // Event that ends the story
track: {
// Events to track within this story
"order:create": { mode: "append" },
"order:complete": { mode: "append" },
}
}
}
};
export default config;
`
$3
`typescript
import { gossamer } from "@dropsilk/gossamer";
async function main() {
// Initialize (loads gossamer.config.ts automatically)
await gossamer.initFromFile();
// Emit events
gossamer.emit("user:login", { userId: "123", name: "Alice" });
gossamer.emit("order:create", { userId: "123", orderId: "A-1" });
// This event is tracked as part of the "UserSession" story for user 123
gossamer.emit("user:logout", { userId: "123" });
// Story "UserSession" for user 123 is now complete and flushed to transports
}
main();
`
Core Concepts
$3
Basic unit of information. Emitted with a name and a payload.
`typescript
gossamer.emit("event:name", { key: "value" });
`
$3
A Story represents a lifecycle. It:
- Starts when a trigger event is observed.
- Uses a correlationKey (e.g., requestId, userId) to bind subsequent events to the story instance.
- Tracks specified events via rules (append, count, ignore).
- Ends when an ender event is observed or it times out.
- Is Flushed to transports as a single, cohesive Trace object containing the full timeline.
$3
Global context that attaches to every emitted event (useful for request IDs, environment info, etc.).
`typescript
gossamer.setContext({ environment: "production" });
// 'environment: production' is now in every event payload
gossamer.emit("something", {});
`
$3
Where your data goes. Defaults to a pretty console output.
Available built-ins:
- ConsolePrettyTransport
- JsonStdoutTransport
- FileTransport
- HttpTransport
Configuration Reference
See src/core/types.ts for full type definitions of GossamerUserConfig`.