annotate_test
Add Grafana annotations for test events on sensors, including start/end times, results, and rate changes. Supports range annotations and dashboard linking with default ramp-test tagging.
Instructions
Add a Grafana annotation on a sensor for test events (start/end/result/rate change). Supports range annotations and dashboard association. Tagged with ramp-test by default.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sensor | No | Sensor hostname | |
| text | Yes | Annotation text | |
| tags | No | Annotation tags (e.g., ["ramp-test", "ns2"]) | |
| time | No | Annotation epoch timestamp (defaults to now) | |
| timeEnd | No | End epoch timestamp for range annotations | |
| dashboardUid | No | Dashboard UID to associate annotation with |
Implementation Reference
- src/services/ramp.ts:749-769 (handler)The annotateTest service method that executes the core logic: resolves the sensor, constructs the annotation body with text/tags/time, and makes a POST request to the Grafana API endpoint '/api/annotations'
async annotateTest(options: { sensor?: string; text: string; tags?: string[]; time?: number; timeEnd?: number; dashboardUid?: string; }): Promise<{ id: number }> { const { info, client } = this.resolveSensor(options.sensor); const now = Date.now(); const body: Record<string, any> = { text: options.text, tags: options.tags ?? ['ramp-test'], time: options.time ?? now, }; if (options.timeEnd) body.timeEnd = options.timeEnd; if (options.dashboardUid) body.dashboardUID = options.dashboardUid; const result = await client.post<{ id: number }>('/api/annotations', body); return result; } - src/ramp-types.ts:98-105 (schema)AnnotateTestSchema Zod schema defining the input validation for the tool with fields: sensor (optional), text (required), tags (optional array), time (optional), timeEnd (optional), and dashboardUid (optional)
export const AnnotateTestSchema = z.object({ sensor: z.string().optional().describe('Sensor hostname'), text: z.string().min(1).describe('Annotation text'), tags: z.array(z.string()).optional().describe('Annotation tags (e.g., ["ramp-test", "ns2"])'), time: z.number().optional().describe('Annotation epoch timestamp (defaults to now)'), timeEnd: z.number().optional().describe('End epoch timestamp for range annotations'), dashboardUid: z.string().optional().describe('Dashboard UID to associate annotation with'), }); - src/tools/ramp.ts:321-358 (registration)Tool registration for 'annotate_test' that defines the tool metadata, parses input using AnnotateTestSchema, calls the rampService.annotateTest method, and handles errors with appropriate response formatting
// 7. annotate_test registry.registerTool( { name: 'annotate_test', description: 'Add a Grafana annotation on a sensor for test events ' + '(start/end/result/rate change). Supports range annotations and dashboard association. Tagged with ramp-test by default.', inputSchema: zodToJsonSchema(AnnotateTestSchema), }, async (request) => { try { const params = AnnotateTestSchema.parse(request.params.arguments); const result = await rampService.annotateTest({ sensor: params.sensor, text: params.text, tags: params.tags, time: params.time, timeEnd: params.timeEnd, dashboardUid: params.dashboardUid, }); return { content: [ { type: 'text', text: `Annotation created (id: ${result.id})`, }, ], }; } catch (error) { const msg = error instanceof Error ? error.message : 'Unknown error'; return { content: [{ type: 'text', text: `Error creating annotation: ${msg}` }], isError: true, }; } }, );