• This feature is currently in beta.
  • Requires maxim-py >= 3.9.x

​
Overview

Attachments let you add files (audio, images, text, etc.) or URLs to your traces and spans in Maxim. This provides extra context for debugging, analytics, and audit trails. All attachments are stored and viewable in the Maxim UI alongside your trace data.

​
How to Add Attachments

You can attach files or URLs to both traces and spans. There are three main types of attachments:
Attachment TypeUse ForExample Parameter(s)
FileAttachmentLocal files (audio, images)path
UrlAttachmentRemote files or imagesurl, mime_type (optional)
FileDataAttachmentData blobs (bytes in memory)data, name, mime_type (opt.)

​
Example: Add Attachments to a Trace

// Create a new trace
const trace = logger.trace({ id: uuid() });
trace.input("test input");

// Attach a local file
trace.addAttachment({
	id: uuid(),
	type: "file",
	path: "./files/wav_audio.wav",
});

// Attach a remote file or image by URL
trace.addAttachment({
	id: uuid(),
	type: "url",
	url: "https://sample-image.com/test-image",
});

// Attach a data blob (e.g., in-memory text)
trace.addAttachment({
	id: uuid(),
	type: "fileData",
	name: "greeting.txt",
	data: Buffer.from("Hello world"),
	mimeType: "text/plain",
});
Tip: You can also add attachments to a span or generation by replacing trace with your span or generation object.

​
Notes

  • You can provide a custom name for each file by passing the name property.
  • Attachments are visible in the Maxim UI for each trace or span.
  • The server detects the MIME type automatically, but you can override it by passing the mime_type parameter.

​
Best Practices

  • File size limit: Each file must be under 50 MB.
  • MIME type: Maxim detects MIME type on the server, but you can override it if needed.
  • Name: Add names to each file to easily detect them while surfing through logs.
If you have further questions, contact support.