contextvm-sdk 0.1.1

Rust SDK for the ContextVM protocol — MCP over Nostr
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

---
title: Logging
description: Logging in the @contextvm/sdk
---

### Logging

The SDK uses Pino for high-performance logging with structured JSON output. By default, logs are written to stderr to comply with the MCP protocol expectations.

#### Basic Usage

[`typescript`](src/content/docs/ts-sdk/core/logging.md:10)

```typescript
import { createLogger } from '@contextvm/sdk/core';

// Create a logger for your module
const logger = createLogger('my-module');

logger.info('Application started');
logger.error('An error occurred', { error: 'details' });
```

#### Configuration Options

[`typescript`](src/content/docs/ts-sdk/core/logging.md:20)

```typescript
import { createLogger, LoggerConfig } from '@contextvm/sdk/core';

const config: LoggerConfig = {
  level: 'debug', // Minimum log level (debug, info, warn, error)
  file: 'app.log', // Optional: log to a file instead of stderr
};

const logger = createLogger('my-module', config);
```

**Note:** Pretty printing is automatically enabled when logs are written to stderr/stdout (not to a file) for better readability during development.

#### Configuring with Environment Variables

The logger can be configured using environment variables, which is useful for adjusting log output without changing the code.

- **`LOG_LEVEL`**: Sets the minimum log level.
  - **Values**: `debug`, `info`, `warn`, `error`.
  - **Default**: `info`.
- **`LOG_DESTINATION`**: Sets the log output destination.
  - **Values**: `stderr` (default), `stdout`, or `file`.
- **`LOG_FILE`**: Specifies the file path when `LOG_DESTINATION` is `file`.
- **`LOG_ENABLED`**: Enables or disables logging.
  - **Values**: `true` (default) or `false`.

##### Configuration in Node.js

[`bash`](src/content/docs/ts-sdk/core/logging.md:49)

```bash
# Set log level to debug
LOG_LEVEL=debug node app.js

# Log to a file instead of the console
LOG_DESTINATION=file LOG_FILE=./app.log node app.js

# Disable logging entirely
LOG_ENABLED=false node app.js
```

##### Configuration in Browsers

[`javascript`](src/content/docs/ts-sdk/core/logging.md:63)

```javascript
// Set this in a <script> tag in your HTML or at the top of your entry point
window.LOG_LEVEL = 'debug';

// Now, when you import and use the SDK, it will use the 'debug' log level.
import { logger } from '@contextvm/sdk';
logger.debug('This is a debug message.');
```

#### Module-specific Loggers

[`typescript`](src/content/docs/ts-sdk/core/logging.md:75)

```typescript
const baseLogger = createLogger('my-app');
const authLogger = baseLogger.withModule('auth');
const dbLogger = baseLogger.withModule('database');

authLogger.info('User login attempt');
dbLogger.debug('Query executed', { query: 'SELECT * FROM users' });
```

#### Conventions and Best Practices

- Log levels:
  - debug: detailed developer-oriented information (traces, SQL queries, internal state).
  - info: high-level lifecycle events and successful operations (startup, shutdown, user actions).
  - warn: unexpected situations that don't stop execution but may need attention.
  - error: failures that require investigation (exceptions, failed requests).
- Use structured fields to add context instead of human-parsed messages. Preferred field names:
  - `module`: module or component name (string).
  - `event`: short event name (string).
  - `txId` / `traceId`: request or trace identifier (string).
  - `userId`: authenticated user id when applicable (string).
  - `durationMs`: operation duration in milliseconds (number).
  - `error`: when logging errors, include an `error` object with `message` and `stack`.
- Avoid logging sensitive data (passwords, secrets, full tokens). Redact or hash when necessary.
- Keep log messages concise and use structured metadata for details.
- Prefer logger.method(message, meta) over string interpolation that embeds structured data into the message.

#### Examples (Best Practice)

[`typescript`](src/content/docs/ts-sdk/core/logging.md:105)

```typescript
logger.info('payment.processed', {
  module: 'payments',
  txId: 'abcd-1234',
  userId: 'user-42',
  amount: 1999,
  currency: 'EUR',
  durationMs: 245,
});

try {
  // do something that throws
} catch (err) {
  logger.error('payment.failed', {
    module: 'payments',
    txId: 'abcd-1234',
    error: { message: err.message, stack: err.stack },
  });
}
```

#### Performance and Safety

- The SDK logger is optimized for minimal allocations. Prefer structured objects over building large strings.
- When logging high-frequency events, consider using lower log levels (info -> debug) or sampling.
- Ensure log files are rotated and monitored if using file destinations.

---

See also: [`src/content/docs/ts-sdk/core/interfaces.md`](src/content/docs/ts-sdk/core/interfaces.md:1)