agentfootprint 2.8.0 → 2.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +157 -394
- package/dist/adapters/observability/agentcore.js +188 -0
- package/dist/adapters/observability/agentcore.js.map +1 -0
- package/dist/esm/adapters/observability/agentcore.js +184 -0
- package/dist/esm/adapters/observability/agentcore.js.map +1 -0
- package/dist/esm/observability-providers.js +37 -0
- package/dist/esm/observability-providers.js.map +1 -0
- package/dist/esm/strategies/index.js +22 -8
- package/dist/esm/strategies/index.js.map +1 -1
- package/dist/observability-providers.js +41 -0
- package/dist/observability-providers.js.map +1 -0
- package/dist/strategies/index.js +22 -8
- package/dist/strategies/index.js.map +1 -1
- package/dist/types/adapters/observability/agentcore.d.ts +86 -0
- package/dist/types/adapters/observability/agentcore.d.ts.map +1 -0
- package/dist/types/observability-providers.d.ts +37 -0
- package/dist/types/observability-providers.d.ts.map +1 -0
- package/dist/types/strategies/index.d.ts +22 -8
- package/dist/types/strategies/index.d.ts.map +1 -1
- package/package.json +10 -1
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* agentcoreObservability — AWS Bedrock AgentCore observability adapter.
|
|
4
|
+
*
|
|
5
|
+
* Ships every `AgentfootprintEvent` to **CloudWatch Logs** in a
|
|
6
|
+
* structured-JSON shape AgentCore's hosted-agent telemetry layer
|
|
7
|
+
* understands. Use when:
|
|
8
|
+
*
|
|
9
|
+
* 1. Your agent runs INSIDE AgentCore — events show up alongside
|
|
10
|
+
* AgentCore's own runtime telemetry in the same log group.
|
|
11
|
+
* 2. Your agent runs OUTSIDE AgentCore but you want to query agent
|
|
12
|
+
* behavior in CloudWatch Insights / X-Ray traces using the same
|
|
13
|
+
* schema AgentCore uses internally.
|
|
14
|
+
*
|
|
15
|
+
* Subpath: `agentfootprint/observability-providers`
|
|
16
|
+
* Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
|
|
17
|
+
* only when this adapter is used; declared via
|
|
18
|
+
* `peerDependenciesMeta.{name}.optional = true`).
|
|
19
|
+
*
|
|
20
|
+
* Pattern: Adapter (GoF) — translates `AgentfootprintEvent` →
|
|
21
|
+
* CloudWatch Logs `PutLogEvents` payloads. Buffers in
|
|
22
|
+
* `exportEvent()` (sync, non-throwing); flushes in `flush()`
|
|
23
|
+
* (async batch). Default flush window: 1s OR 10 KB,
|
|
24
|
+
* whichever first — matches CloudWatch's own optimal batch.
|
|
25
|
+
*
|
|
26
|
+
* @example Basic
|
|
27
|
+
* ```ts
|
|
28
|
+
* import { agentcoreObservability } from 'agentfootprint/observability-providers';
|
|
29
|
+
* import { microtaskBatchDriver } from 'footprintjs/detach';
|
|
30
|
+
*
|
|
31
|
+
* agent.enable.observability({
|
|
32
|
+
* strategy: agentcoreObservability({
|
|
33
|
+
* region: 'us-east-1',
|
|
34
|
+
* logGroupName: '/agentfootprint/my-agent',
|
|
35
|
+
* logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
|
|
36
|
+
* }),
|
|
37
|
+
* detach: { driver: microtaskBatchDriver, mode: 'forget' },
|
|
38
|
+
* });
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* @example Test injection (skip SDK require entirely)
|
|
42
|
+
* ```ts
|
|
43
|
+
* agentcoreObservability({
|
|
44
|
+
* _client: {
|
|
45
|
+
* putLogEvents: async (input) => { capturedBatches.push(input); },
|
|
46
|
+
* },
|
|
47
|
+
* });
|
|
48
|
+
* ```
|
|
49
|
+
*/
|
|
50
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
51
|
+
exports.agentcoreObservability = void 0;
|
|
52
|
+
const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
|
|
53
|
+
// ─── Strategy factory ────────────────────────────────────────────────
|
|
54
|
+
function agentcoreObservability(opts) {
|
|
55
|
+
if (!opts.logGroupName) {
|
|
56
|
+
throw new TypeError(`[agentcoreObservability] \`logGroupName\` is required. ` +
|
|
57
|
+
`Pass an existing CloudWatch log group, e.g. '/agentfootprint/my-agent'.`);
|
|
58
|
+
}
|
|
59
|
+
const logStreamName = opts.logStreamName ?? 'agentfootprint';
|
|
60
|
+
const maxBatchEvents = opts.maxBatchEvents ?? 100;
|
|
61
|
+
const maxBatchBytes = opts.maxBatchBytes ?? 10_240;
|
|
62
|
+
const flushIntervalMs = opts.flushIntervalMs ?? 1000;
|
|
63
|
+
// Buffered batch — drained by `flush()` / size-trigger / time-trigger.
|
|
64
|
+
const buffer = [];
|
|
65
|
+
let bufferBytes = 0;
|
|
66
|
+
let lastFlushPromise = Promise.resolve();
|
|
67
|
+
let timer;
|
|
68
|
+
let stopped = false;
|
|
69
|
+
let onErrorHook;
|
|
70
|
+
// Lazy-resolved on first flush so consumers who never trigger a
|
|
71
|
+
// flush (because nothing was emitted) don't even hit the SDK.
|
|
72
|
+
let client = opts._client;
|
|
73
|
+
function ensureClient() {
|
|
74
|
+
if (client)
|
|
75
|
+
return client;
|
|
76
|
+
client = createCloudWatchClient(opts.region);
|
|
77
|
+
return client;
|
|
78
|
+
}
|
|
79
|
+
function scheduleTimedFlush() {
|
|
80
|
+
if (timer || flushIntervalMs <= 0 || stopped)
|
|
81
|
+
return;
|
|
82
|
+
timer = setTimeout(() => {
|
|
83
|
+
timer = undefined;
|
|
84
|
+
void doFlush();
|
|
85
|
+
}, flushIntervalMs);
|
|
86
|
+
}
|
|
87
|
+
async function doFlush() {
|
|
88
|
+
if (buffer.length === 0 || stopped)
|
|
89
|
+
return;
|
|
90
|
+
// Snapshot + clear so concurrent emits during the in-flight put
|
|
91
|
+
// accumulate into the next batch.
|
|
92
|
+
const batch = buffer.splice(0);
|
|
93
|
+
bufferBytes = 0;
|
|
94
|
+
try {
|
|
95
|
+
await ensureClient().putLogEvents({
|
|
96
|
+
logGroupName: opts.logGroupName,
|
|
97
|
+
logStreamName,
|
|
98
|
+
logEvents: batch,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
catch (err) {
|
|
102
|
+
onErrorHook?.(err instanceof Error ? err : new Error(String(err)));
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
function enqueue(event) {
|
|
106
|
+
if (stopped)
|
|
107
|
+
return;
|
|
108
|
+
const message = JSON.stringify(event);
|
|
109
|
+
const bytes = Buffer.byteLength(message, 'utf8');
|
|
110
|
+
buffer.push({ timestamp: Date.now(), message });
|
|
111
|
+
bufferBytes += bytes;
|
|
112
|
+
if (buffer.length >= maxBatchEvents || bufferBytes >= maxBatchBytes) {
|
|
113
|
+
// Size trigger — flush immediately. Chain onto last to preserve
|
|
114
|
+
// CloudWatch's per-stream ordering requirement.
|
|
115
|
+
lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
|
|
116
|
+
}
|
|
117
|
+
else {
|
|
118
|
+
scheduleTimedFlush();
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
return {
|
|
122
|
+
name: 'agentcore',
|
|
123
|
+
capabilities: { events: true, logs: true },
|
|
124
|
+
exportEvent: enqueue,
|
|
125
|
+
async flush() {
|
|
126
|
+
// Drain anything pending. Awaits both an in-flight put AND any
|
|
127
|
+
// newly-buffered events that arrived during it.
|
|
128
|
+
while (buffer.length > 0 || lastFlushPromise !== Promise.resolve()) {
|
|
129
|
+
const before = lastFlushPromise;
|
|
130
|
+
await before;
|
|
131
|
+
if (buffer.length > 0) {
|
|
132
|
+
lastFlushPromise = doFlush();
|
|
133
|
+
}
|
|
134
|
+
// Loop one more pass if the chained doFlush() queued more
|
|
135
|
+
// work, then bail.
|
|
136
|
+
if (lastFlushPromise === before && buffer.length === 0)
|
|
137
|
+
break;
|
|
138
|
+
}
|
|
139
|
+
},
|
|
140
|
+
stop() {
|
|
141
|
+
stopped = true;
|
|
142
|
+
if (timer) {
|
|
143
|
+
clearTimeout(timer);
|
|
144
|
+
timer = undefined;
|
|
145
|
+
}
|
|
146
|
+
},
|
|
147
|
+
_onError(err, event) {
|
|
148
|
+
// Capture for use inside doFlush (the strategy doesn't know what
|
|
149
|
+
// the consumer's error sink is unless they wire `_onError` via
|
|
150
|
+
// the strategy options. We store it on this hook so put-failures
|
|
151
|
+
// route correctly).
|
|
152
|
+
onErrorHook =
|
|
153
|
+
onErrorHook ??
|
|
154
|
+
((e) => {
|
|
155
|
+
// eslint-disable-next-line no-console
|
|
156
|
+
console.error('[agentcoreObservability] flush failed:', e.message);
|
|
157
|
+
});
|
|
158
|
+
onErrorHook(err, event);
|
|
159
|
+
},
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
exports.agentcoreObservability = agentcoreObservability;
|
|
163
|
+
// ─── SDK client construction (lazy) ──────────────────────────────────
|
|
164
|
+
function createCloudWatchClient(region) {
|
|
165
|
+
let mod;
|
|
166
|
+
try {
|
|
167
|
+
mod = (0, lazyRequire_js_1.lazyRequire)('@aws-sdk/client-cloudwatch-logs');
|
|
168
|
+
}
|
|
169
|
+
catch {
|
|
170
|
+
throw new Error('agentcoreObservability requires the `@aws-sdk/client-cloudwatch-logs` peer dependency.\n' +
|
|
171
|
+
' Install: npm install @aws-sdk/client-cloudwatch-logs\n' +
|
|
172
|
+
' Or pass `_client` for test injection.');
|
|
173
|
+
}
|
|
174
|
+
if (!mod.CloudWatchLogsClient || !mod.PutLogEventsCommand) {
|
|
175
|
+
throw new Error('agentcoreObservability: `@aws-sdk/client-cloudwatch-logs` is installed but ' +
|
|
176
|
+
'`CloudWatchLogsClient` / `PutLogEventsCommand` was not found. Update the SDK.');
|
|
177
|
+
}
|
|
178
|
+
const sdkClient = new mod.CloudWatchLogsClient({ ...(region && { region }) });
|
|
179
|
+
return {
|
|
180
|
+
async putLogEvents(input) {
|
|
181
|
+
// Cast the SDK constructor to the call shape — same trick as the
|
|
182
|
+
// memory adapter to stay forward-compat with SDK shape drift.
|
|
183
|
+
const cmd = new mod.PutLogEventsCommand(input);
|
|
184
|
+
await sdkClient.send(cmd);
|
|
185
|
+
},
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
//# sourceMappingURL=agentcore.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agentcoreObservability — AWS Bedrock AgentCore observability adapter.
|
|
3
|
+
*
|
|
4
|
+
* Ships every `AgentfootprintEvent` to **CloudWatch Logs** in a
|
|
5
|
+
* structured-JSON shape AgentCore's hosted-agent telemetry layer
|
|
6
|
+
* understands. Use when:
|
|
7
|
+
*
|
|
8
|
+
* 1. Your agent runs INSIDE AgentCore — events show up alongside
|
|
9
|
+
* AgentCore's own runtime telemetry in the same log group.
|
|
10
|
+
* 2. Your agent runs OUTSIDE AgentCore but you want to query agent
|
|
11
|
+
* behavior in CloudWatch Insights / X-Ray traces using the same
|
|
12
|
+
* schema AgentCore uses internally.
|
|
13
|
+
*
|
|
14
|
+
* Subpath: `agentfootprint/observability-providers`
|
|
15
|
+
* Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
|
|
16
|
+
* only when this adapter is used; declared via
|
|
17
|
+
* `peerDependenciesMeta.{name}.optional = true`).
|
|
18
|
+
*
|
|
19
|
+
* Pattern: Adapter (GoF) — translates `AgentfootprintEvent` →
|
|
20
|
+
* CloudWatch Logs `PutLogEvents` payloads. Buffers in
|
|
21
|
+
* `exportEvent()` (sync, non-throwing); flushes in `flush()`
|
|
22
|
+
* (async batch). Default flush window: 1s OR 10 KB,
|
|
23
|
+
* whichever first — matches CloudWatch's own optimal batch.
|
|
24
|
+
*
|
|
25
|
+
* @example Basic
|
|
26
|
+
* ```ts
|
|
27
|
+
* import { agentcoreObservability } from 'agentfootprint/observability-providers';
|
|
28
|
+
* import { microtaskBatchDriver } from 'footprintjs/detach';
|
|
29
|
+
*
|
|
30
|
+
* agent.enable.observability({
|
|
31
|
+
* strategy: agentcoreObservability({
|
|
32
|
+
* region: 'us-east-1',
|
|
33
|
+
* logGroupName: '/agentfootprint/my-agent',
|
|
34
|
+
* logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
|
|
35
|
+
* }),
|
|
36
|
+
* detach: { driver: microtaskBatchDriver, mode: 'forget' },
|
|
37
|
+
* });
|
|
38
|
+
* ```
|
|
39
|
+
*
|
|
40
|
+
* @example Test injection (skip SDK require entirely)
|
|
41
|
+
* ```ts
|
|
42
|
+
* agentcoreObservability({
|
|
43
|
+
* _client: {
|
|
44
|
+
* putLogEvents: async (input) => { capturedBatches.push(input); },
|
|
45
|
+
* },
|
|
46
|
+
* });
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
import { lazyRequire } from '../../lib/lazyRequire.js';
|
|
50
|
+
// ─── Strategy factory ────────────────────────────────────────────────
|
|
51
|
+
export function agentcoreObservability(opts) {
|
|
52
|
+
if (!opts.logGroupName) {
|
|
53
|
+
throw new TypeError(`[agentcoreObservability] \`logGroupName\` is required. ` +
|
|
54
|
+
`Pass an existing CloudWatch log group, e.g. '/agentfootprint/my-agent'.`);
|
|
55
|
+
}
|
|
56
|
+
const logStreamName = opts.logStreamName ?? 'agentfootprint';
|
|
57
|
+
const maxBatchEvents = opts.maxBatchEvents ?? 100;
|
|
58
|
+
const maxBatchBytes = opts.maxBatchBytes ?? 10_240;
|
|
59
|
+
const flushIntervalMs = opts.flushIntervalMs ?? 1000;
|
|
60
|
+
// Buffered batch — drained by `flush()` / size-trigger / time-trigger.
|
|
61
|
+
const buffer = [];
|
|
62
|
+
let bufferBytes = 0;
|
|
63
|
+
let lastFlushPromise = Promise.resolve();
|
|
64
|
+
let timer;
|
|
65
|
+
let stopped = false;
|
|
66
|
+
let onErrorHook;
|
|
67
|
+
// Lazy-resolved on first flush so consumers who never trigger a
|
|
68
|
+
// flush (because nothing was emitted) don't even hit the SDK.
|
|
69
|
+
let client = opts._client;
|
|
70
|
+
function ensureClient() {
|
|
71
|
+
if (client)
|
|
72
|
+
return client;
|
|
73
|
+
client = createCloudWatchClient(opts.region);
|
|
74
|
+
return client;
|
|
75
|
+
}
|
|
76
|
+
function scheduleTimedFlush() {
|
|
77
|
+
if (timer || flushIntervalMs <= 0 || stopped)
|
|
78
|
+
return;
|
|
79
|
+
timer = setTimeout(() => {
|
|
80
|
+
timer = undefined;
|
|
81
|
+
void doFlush();
|
|
82
|
+
}, flushIntervalMs);
|
|
83
|
+
}
|
|
84
|
+
async function doFlush() {
|
|
85
|
+
if (buffer.length === 0 || stopped)
|
|
86
|
+
return;
|
|
87
|
+
// Snapshot + clear so concurrent emits during the in-flight put
|
|
88
|
+
// accumulate into the next batch.
|
|
89
|
+
const batch = buffer.splice(0);
|
|
90
|
+
bufferBytes = 0;
|
|
91
|
+
try {
|
|
92
|
+
await ensureClient().putLogEvents({
|
|
93
|
+
logGroupName: opts.logGroupName,
|
|
94
|
+
logStreamName,
|
|
95
|
+
logEvents: batch,
|
|
96
|
+
});
|
|
97
|
+
}
|
|
98
|
+
catch (err) {
|
|
99
|
+
onErrorHook?.(err instanceof Error ? err : new Error(String(err)));
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
function enqueue(event) {
|
|
103
|
+
if (stopped)
|
|
104
|
+
return;
|
|
105
|
+
const message = JSON.stringify(event);
|
|
106
|
+
const bytes = Buffer.byteLength(message, 'utf8');
|
|
107
|
+
buffer.push({ timestamp: Date.now(), message });
|
|
108
|
+
bufferBytes += bytes;
|
|
109
|
+
if (buffer.length >= maxBatchEvents || bufferBytes >= maxBatchBytes) {
|
|
110
|
+
// Size trigger — flush immediately. Chain onto last to preserve
|
|
111
|
+
// CloudWatch's per-stream ordering requirement.
|
|
112
|
+
lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
|
|
113
|
+
}
|
|
114
|
+
else {
|
|
115
|
+
scheduleTimedFlush();
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
return {
|
|
119
|
+
name: 'agentcore',
|
|
120
|
+
capabilities: { events: true, logs: true },
|
|
121
|
+
exportEvent: enqueue,
|
|
122
|
+
async flush() {
|
|
123
|
+
// Drain anything pending. Awaits both an in-flight put AND any
|
|
124
|
+
// newly-buffered events that arrived during it.
|
|
125
|
+
while (buffer.length > 0 || lastFlushPromise !== Promise.resolve()) {
|
|
126
|
+
const before = lastFlushPromise;
|
|
127
|
+
await before;
|
|
128
|
+
if (buffer.length > 0) {
|
|
129
|
+
lastFlushPromise = doFlush();
|
|
130
|
+
}
|
|
131
|
+
// Loop one more pass if the chained doFlush() queued more
|
|
132
|
+
// work, then bail.
|
|
133
|
+
if (lastFlushPromise === before && buffer.length === 0)
|
|
134
|
+
break;
|
|
135
|
+
}
|
|
136
|
+
},
|
|
137
|
+
stop() {
|
|
138
|
+
stopped = true;
|
|
139
|
+
if (timer) {
|
|
140
|
+
clearTimeout(timer);
|
|
141
|
+
timer = undefined;
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
_onError(err, event) {
|
|
145
|
+
// Capture for use inside doFlush (the strategy doesn't know what
|
|
146
|
+
// the consumer's error sink is unless they wire `_onError` via
|
|
147
|
+
// the strategy options. We store it on this hook so put-failures
|
|
148
|
+
// route correctly).
|
|
149
|
+
onErrorHook =
|
|
150
|
+
onErrorHook ??
|
|
151
|
+
((e) => {
|
|
152
|
+
// eslint-disable-next-line no-console
|
|
153
|
+
console.error('[agentcoreObservability] flush failed:', e.message);
|
|
154
|
+
});
|
|
155
|
+
onErrorHook(err, event);
|
|
156
|
+
},
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
// ─── SDK client construction (lazy) ──────────────────────────────────
|
|
160
|
+
function createCloudWatchClient(region) {
|
|
161
|
+
let mod;
|
|
162
|
+
try {
|
|
163
|
+
mod = lazyRequire('@aws-sdk/client-cloudwatch-logs');
|
|
164
|
+
}
|
|
165
|
+
catch {
|
|
166
|
+
throw new Error('agentcoreObservability requires the `@aws-sdk/client-cloudwatch-logs` peer dependency.\n' +
|
|
167
|
+
' Install: npm install @aws-sdk/client-cloudwatch-logs\n' +
|
|
168
|
+
' Or pass `_client` for test injection.');
|
|
169
|
+
}
|
|
170
|
+
if (!mod.CloudWatchLogsClient || !mod.PutLogEventsCommand) {
|
|
171
|
+
throw new Error('agentcoreObservability: `@aws-sdk/client-cloudwatch-logs` is installed but ' +
|
|
172
|
+
'`CloudWatchLogsClient` / `PutLogEventsCommand` was not found. Update the SDK.');
|
|
173
|
+
}
|
|
174
|
+
const sdkClient = new mod.CloudWatchLogsClient({ ...(region && { region }) });
|
|
175
|
+
return {
|
|
176
|
+
async putLogEvents(input) {
|
|
177
|
+
// Cast the SDK constructor to the call shape — same trick as the
|
|
178
|
+
// memory adapter to stay forward-compat with SDK shape drift.
|
|
179
|
+
const cmd = new mod.PutLogEventsCommand(input);
|
|
180
|
+
await sdkClient.send(cmd);
|
|
181
|
+
},
|
|
182
|
+
};
|
|
183
|
+
}
|
|
184
|
+
//# sourceMappingURL=agentcore.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agentfootprint/observability-providers — vendor observability strategies.
|
|
3
|
+
*
|
|
4
|
+
* Grouped subpath following the parallel-providers pattern v2.5
|
|
5
|
+
* established for `llm-providers` / `tool-providers` /
|
|
6
|
+
* `memory-providers`. Adding a new vendor adds an export here, NOT
|
|
7
|
+
* a new subpath — keeps `package.json#exports` from sprawling.
|
|
8
|
+
*
|
|
9
|
+
* Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
|
|
10
|
+
* so consumers who never call a particular factory don't have to
|
|
11
|
+
* install that SDK. Peer-deps are declared in package.json with
|
|
12
|
+
* `peerDependenciesMeta.{name}.optional = true`.
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```ts
|
|
16
|
+
* import { agentcoreObservability } from 'agentfootprint/observability-providers';
|
|
17
|
+
* import { microtaskBatchDriver } from 'footprintjs/detach';
|
|
18
|
+
*
|
|
19
|
+
* agent.enable.observability({
|
|
20
|
+
* strategy: agentcoreObservability({
|
|
21
|
+
* region: 'us-east-1',
|
|
22
|
+
* logGroupName: '/agentfootprint/my-agent',
|
|
23
|
+
* }),
|
|
24
|
+
* // Recommended — keeps the agent loop unblocked by network latency.
|
|
25
|
+
* detach: { driver: microtaskBatchDriver, mode: 'forget' },
|
|
26
|
+
* });
|
|
27
|
+
* ```
|
|
28
|
+
*
|
|
29
|
+
* Roadmap:
|
|
30
|
+
* - agentcoreObservability ← v2.8.1 (this release)
|
|
31
|
+
* - cloudwatchObservability ← v2.8.2
|
|
32
|
+
* - xrayObservability ← v2.8.3
|
|
33
|
+
* - otelObservability ← v2.9.x
|
|
34
|
+
* - datadogObservability ← v2.9.x
|
|
35
|
+
*/
|
|
36
|
+
export { agentcoreObservability, } from './adapters/observability/agentcore.js';
|
|
37
|
+
//# sourceMappingURL=observability-providers.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC"}
|
|
@@ -7,14 +7,28 @@
|
|
|
7
7
|
* - `types.ts` — typed interfaces (Observability, Cost, LiveStatus, Lens)
|
|
8
8
|
* - `defaults/` — the 4 in-core default strategies
|
|
9
9
|
*
|
|
10
|
-
* Vendor strategies ship
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* - `agentfootprint/observability-
|
|
16
|
-
*
|
|
17
|
-
*
|
|
10
|
+
* Vendor strategies ship under three GROUPED subpaths (matching the
|
|
11
|
+
* parallel-providers pattern v2.5 established for `llm-providers` /
|
|
12
|
+
* `tool-providers` / `memory-providers`). Each subpath holds N
|
|
13
|
+
* vendor-named factories — adding a vendor never adds a new subpath:
|
|
14
|
+
*
|
|
15
|
+
* - `agentfootprint/observability-providers`
|
|
16
|
+
* agentcoreObservability (v2.8.1)
|
|
17
|
+
* cloudwatchObservability (v2.8.2)
|
|
18
|
+
* xrayObservability (v2.8.3)
|
|
19
|
+
* otelObservability (v2.9.x)
|
|
20
|
+
* datadogObservability (v2.9.x)
|
|
21
|
+
*
|
|
22
|
+
* - `agentfootprint/cost-providers`
|
|
23
|
+
* stripeCost (v2.10.x)
|
|
24
|
+
*
|
|
25
|
+
* - `agentfootprint/lens-providers`
|
|
26
|
+
* browserLens / cliLens (v2.12.x)
|
|
27
|
+
*
|
|
28
|
+
* Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
|
|
29
|
+
* so consumers who never call a particular factory don't have to
|
|
30
|
+
* install that SDK. Peer-deps are declared in package.json with
|
|
31
|
+
* `peerDependenciesMeta.{name}.optional = true`.
|
|
18
32
|
*/
|
|
19
33
|
export * from './types.js';
|
|
20
34
|
export * from './defaults/index.js';
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjG,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,wBAAwB,GAIzB,MAAM,aAAa,CAAC"}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* agentfootprint/observability-providers — vendor observability strategies.
|
|
4
|
+
*
|
|
5
|
+
* Grouped subpath following the parallel-providers pattern v2.5
|
|
6
|
+
* established for `llm-providers` / `tool-providers` /
|
|
7
|
+
* `memory-providers`. Adding a new vendor adds an export here, NOT
|
|
8
|
+
* a new subpath — keeps `package.json#exports` from sprawling.
|
|
9
|
+
*
|
|
10
|
+
* Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
|
|
11
|
+
* so consumers who never call a particular factory don't have to
|
|
12
|
+
* install that SDK. Peer-deps are declared in package.json with
|
|
13
|
+
* `peerDependenciesMeta.{name}.optional = true`.
|
|
14
|
+
*
|
|
15
|
+
* @example
|
|
16
|
+
* ```ts
|
|
17
|
+
* import { agentcoreObservability } from 'agentfootprint/observability-providers';
|
|
18
|
+
* import { microtaskBatchDriver } from 'footprintjs/detach';
|
|
19
|
+
*
|
|
20
|
+
* agent.enable.observability({
|
|
21
|
+
* strategy: agentcoreObservability({
|
|
22
|
+
* region: 'us-east-1',
|
|
23
|
+
* logGroupName: '/agentfootprint/my-agent',
|
|
24
|
+
* }),
|
|
25
|
+
* // Recommended — keeps the agent loop unblocked by network latency.
|
|
26
|
+
* detach: { driver: microtaskBatchDriver, mode: 'forget' },
|
|
27
|
+
* });
|
|
28
|
+
* ```
|
|
29
|
+
*
|
|
30
|
+
* Roadmap:
|
|
31
|
+
* - agentcoreObservability ← v2.8.1 (this release)
|
|
32
|
+
* - cloudwatchObservability ← v2.8.2
|
|
33
|
+
* - xrayObservability ← v2.8.3
|
|
34
|
+
* - otelObservability ← v2.9.x
|
|
35
|
+
* - datadogObservability ← v2.9.x
|
|
36
|
+
*/
|
|
37
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
38
|
+
exports.agentcoreObservability = void 0;
|
|
39
|
+
var agentcore_js_1 = require("./adapters/observability/agentcore.js");
|
|
40
|
+
Object.defineProperty(exports, "agentcoreObservability", { enumerable: true, get: function () { return agentcore_js_1.agentcoreObservability; } });
|
|
41
|
+
//# sourceMappingURL=observability-providers.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../src/observability-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,sEAG+C;AAF7C,sHAAA,sBAAsB,OAAA"}
|
package/dist/strategies/index.js
CHANGED
|
@@ -8,14 +8,28 @@
|
|
|
8
8
|
* - `types.ts` — typed interfaces (Observability, Cost, LiveStatus, Lens)
|
|
9
9
|
* - `defaults/` — the 4 in-core default strategies
|
|
10
10
|
*
|
|
11
|
-
* Vendor strategies ship
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* - `agentfootprint/observability-
|
|
17
|
-
*
|
|
18
|
-
*
|
|
11
|
+
* Vendor strategies ship under three GROUPED subpaths (matching the
|
|
12
|
+
* parallel-providers pattern v2.5 established for `llm-providers` /
|
|
13
|
+
* `tool-providers` / `memory-providers`). Each subpath holds N
|
|
14
|
+
* vendor-named factories — adding a vendor never adds a new subpath:
|
|
15
|
+
*
|
|
16
|
+
* - `agentfootprint/observability-providers`
|
|
17
|
+
* agentcoreObservability (v2.8.1)
|
|
18
|
+
* cloudwatchObservability (v2.8.2)
|
|
19
|
+
* xrayObservability (v2.8.3)
|
|
20
|
+
* otelObservability (v2.9.x)
|
|
21
|
+
* datadogObservability (v2.9.x)
|
|
22
|
+
*
|
|
23
|
+
* - `agentfootprint/cost-providers`
|
|
24
|
+
* stripeCost (v2.10.x)
|
|
25
|
+
*
|
|
26
|
+
* - `agentfootprint/lens-providers`
|
|
27
|
+
* browserLens / cliLens (v2.12.x)
|
|
28
|
+
*
|
|
29
|
+
* Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
|
|
30
|
+
* so consumers who never call a particular factory don't have to
|
|
31
|
+
* install that SDK. Peer-deps are declared in package.json with
|
|
32
|
+
* `peerDependenciesMeta.{name}.optional = true`.
|
|
19
33
|
*/
|
|
20
34
|
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
21
35
|
if (k2 === undefined) k2 = k;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/strategies/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/strategies/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;;;;;;;;;;;;;;;AAEH,6CAA2B;AAC3B,sDAAoC;AACpC,2CAAiG;AAAxF,kHAAA,oBAAoB,OAAA;AAAE,yGAAA,WAAW,OAAA;AAAE,+GAAA,iBAAiB,OAAA;AAAE,yGAAA,WAAW,OAAA;AAC1E,yCAOqB;AANnB,wHAAA,2BAA2B,OAAA;AAC3B,+GAAA,kBAAkB,OAAA;AAClB,qHAAA,wBAAwB,OAAA"}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* agentcoreObservability — AWS Bedrock AgentCore observability adapter.
|
|
3
|
+
*
|
|
4
|
+
* Ships every `AgentfootprintEvent` to **CloudWatch Logs** in a
|
|
5
|
+
* structured-JSON shape AgentCore's hosted-agent telemetry layer
|
|
6
|
+
* understands. Use when:
|
|
7
|
+
*
|
|
8
|
+
* 1. Your agent runs INSIDE AgentCore — events show up alongside
|
|
9
|
+
* AgentCore's own runtime telemetry in the same log group.
|
|
10
|
+
* 2. Your agent runs OUTSIDE AgentCore but you want to query agent
|
|
11
|
+
* behavior in CloudWatch Insights / X-Ray traces using the same
|
|
12
|
+
* schema AgentCore uses internally.
|
|
13
|
+
*
|
|
14
|
+
* Subpath: `agentfootprint/observability-providers`
|
|
15
|
+
* Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
|
|
16
|
+
* only when this adapter is used; declared via
|
|
17
|
+
* `peerDependenciesMeta.{name}.optional = true`).
|
|
18
|
+
*
|
|
19
|
+
* Pattern: Adapter (GoF) — translates `AgentfootprintEvent` →
|
|
20
|
+
* CloudWatch Logs `PutLogEvents` payloads. Buffers in
|
|
21
|
+
* `exportEvent()` (sync, non-throwing); flushes in `flush()`
|
|
22
|
+
* (async batch). Default flush window: 1s OR 10 KB,
|
|
23
|
+
* whichever first — matches CloudWatch's own optimal batch.
|
|
24
|
+
*
|
|
25
|
+
* @example Basic
|
|
26
|
+
* ```ts
|
|
27
|
+
* import { agentcoreObservability } from 'agentfootprint/observability-providers';
|
|
28
|
+
* import { microtaskBatchDriver } from 'footprintjs/detach';
|
|
29
|
+
*
|
|
30
|
+
* agent.enable.observability({
|
|
31
|
+
* strategy: agentcoreObservability({
|
|
32
|
+
* region: 'us-east-1',
|
|
33
|
+
* logGroupName: '/agentfootprint/my-agent',
|
|
34
|
+
* logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
|
|
35
|
+
* }),
|
|
36
|
+
* detach: { driver: microtaskBatchDriver, mode: 'forget' },
|
|
37
|
+
* });
|
|
38
|
+
* ```
|
|
39
|
+
*
|
|
40
|
+
* @example Test injection (skip SDK require entirely)
|
|
41
|
+
* ```ts
|
|
42
|
+
* agentcoreObservability({
|
|
43
|
+
* _client: {
|
|
44
|
+
* putLogEvents: async (input) => { capturedBatches.push(input); },
|
|
45
|
+
* },
|
|
46
|
+
* });
|
|
47
|
+
* ```
|
|
48
|
+
*/
|
|
49
|
+
import type { ObservabilityStrategy } from '../../strategies/types.js';
|
|
50
|
+
export interface AgentcoreObservabilityOptions {
|
|
51
|
+
/** AWS region. Falls back to AWS_REGION / AWS_DEFAULT_REGION env. */
|
|
52
|
+
readonly region?: string;
|
|
53
|
+
/** CloudWatch Logs log group. **Required.** Must exist or your IAM
|
|
54
|
+
* role must allow `logs:CreateLogGroup`. */
|
|
55
|
+
readonly logGroupName: string;
|
|
56
|
+
/** CloudWatch Logs log stream within the group. Conventionally
|
|
57
|
+
* `<host>/<startTime>` so multi-instance deployments don't collide.
|
|
58
|
+
* Created on first put if it doesn't exist (or your role must
|
|
59
|
+
* allow `logs:CreateLogStream`). Defaults to `agentfootprint`. */
|
|
60
|
+
readonly logStreamName?: string;
|
|
61
|
+
/** Max events buffered before forced flush. Default 100. */
|
|
62
|
+
readonly maxBatchEvents?: number;
|
|
63
|
+
/** Max payload bytes (UTF-8) buffered before forced flush. Default
|
|
64
|
+
* 10240 (10 KB). CloudWatch hard caps at 1 MB / batch but we keep
|
|
65
|
+
* the default low so latency stays bounded. */
|
|
66
|
+
readonly maxBatchBytes?: number;
|
|
67
|
+
/** Forced-flush interval when traffic is sparse. Default 1000ms.
|
|
68
|
+
* `0` disables time-based flush — only size triggers fire. */
|
|
69
|
+
readonly flushIntervalMs?: number;
|
|
70
|
+
/** Test injection — bypasses SDK lazy-require entirely. When set,
|
|
71
|
+
* `region` / IAM are ignored. */
|
|
72
|
+
readonly _client?: CloudWatchLikeClient;
|
|
73
|
+
}
|
|
74
|
+
interface CloudWatchLikeClient {
|
|
75
|
+
putLogEvents(input: {
|
|
76
|
+
logGroupName: string;
|
|
77
|
+
logStreamName: string;
|
|
78
|
+
logEvents: ReadonlyArray<{
|
|
79
|
+
timestamp: number;
|
|
80
|
+
message: string;
|
|
81
|
+
}>;
|
|
82
|
+
}): Promise<unknown>;
|
|
83
|
+
}
|
|
84
|
+
export declare function agentcoreObservability(opts: AgentcoreObservabilityOptions): ObservabilityStrategy;
|
|
85
|
+
export {};
|
|
86
|
+
//# sourceMappingURL=agentcore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,6BAA6B;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iDAC6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;uEAGmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;oDAEgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;mEAC+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;sCACkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAID,UAAU,oBAAoB;IAC5B,YAAY,CAAC,KAAK,EAAE;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,aAAa,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAUD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,qBAAqB,CA8GjG"}
|