feat: Artifacts — attach binary blobs to spans by adriangb · Pull Request #1931 · pydantic/logfire

adriangb · 2026-05-18T07:06:48Z

What

Adds logfire.Artifact — attach a binary blob (image, audio, PDF, large JSON) to a span. The blob is uploaded to object storage out of band; the span carries only a small content-addressed (sha256) reference, so it is not subject to attribute size limits and does not bloat telemetry.

This is the SDK side. The backend side ships separately in the platform repo (PR linked below once open).

Usage

import logfire

logfire.configure()

logfire.info('chart generated', chart=logfire.Artifact.from_file('chart.png'))
logfire.info('thumbnail', image=logfire.Artifact(png_bytes, content_type='image/png'))

Construct from bytes, a file path (Artifact.from_file), or a binary handle (Artifact.from_file_handle — handles temp/spooled files).
upload is chosen per artifact:
- background (default) — never blocks the caller. If the upload queue is over its byte budget, the artifact is dropped with a warning rather than applying backpressure.
- sync — uploaded inline; the call returns once the blob is stored, so the source can be freed immediately.

How it works

An artifact serializes to a reference object ({"type": "logfire.artifact", "sha256": …}) via the existing json_schema / json_encoder hooks. A background uploader runs the register → PUT → finalize handshake against the backend; signed object-store URLs are PUT to without the bearer token.

Changes

logfire/_internal/artifacts.py — Artifact + the ArtifactSource abstraction (bytes / path; designed so streaming sources can be added later).
logfire/_internal/exporters/artifact_uploader.py — background uploader (bounded queue, drop-on-full).
json_schema / json_encoder / main / config hooks; Artifact + UploadMode exports.
logfire-api stubs regenerated; docs page at reference/advanced/artifacts.md.

Verification

tests/test_artifacts.py — 14 tests pass (construction from each source, schema/encoder hooks, span integration, uploader sync/background/dedup/drop-on-full/error-swallowing). ruff + pyright clean.

Note: test_logfire_api.py::test_runtime[with_logfire] currently fails on an unrelated dspy DeprecationWarning raised by instrument_dspy — pre-existing, not introduced here.

🤖 Generated with Claude Code

`logfire.Artifact` attaches an image, audio clip, PDF, or large JSON payload to a span. The blob is uploaded to object storage out of band (sync or in the background, chosen per artifact); the span carries only a small content-addressed reference, so it is not subject to attribute size limits. - `Artifact` from bytes, a file path, or a binary handle. - `upload='background'` (default — never blocks the caller; drops with a warning if the upload queue is full) or `upload='sync'` (inline, guaranteed delivery, frees the source immediately). - `json_schema` / `json_encoder` hooks: an artifact serializes to a reference object; the blob upload is brokered out of band. - `logfire-api` stubs and a docs page. The backend side ships separately in the platform repo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

adriangb · 2026-05-18T07:07:09Z

Backend side: pydantic/platform#21850

cloudflare-workers-and-pages · 2026-05-18T07:07:53Z

Deploying logfire-docs with Cloudflare Pages

Latest commit:	`ead1587`
Status:	✅ Deploy successful!
Preview URL:	https://2206d6f6.logfire-docs.pages.dev
Branch Preview URL:	https://feat-artifacts.logfire-docs.pages.dev

View logs

alexmojaki · 2026-05-18T09:36:46Z

Please don't generate pyi files in PRs, they're just clutter. the CLAUDE.md should probably make this more explicit.

alexmojaki · 2026-05-18T09:37:39Z

+  logging call never blocks. If uploads cannot keep up, queued artifacts are dropped
+  with a warning rather than stalling your program.
+- **`sync`** — the upload runs inline; the logging call returns only once the blob is
+  stored. Use this when you need delivery guaranteed, or when you want to free the


Delivery is far from guaranteed with sync, it still just silently swallows request exceptions without retrying.

Do you think we should make the guarantee stronger (error) or make the docstrings match current impl?

i think we eventually want a stronger guarantee, but it doesn't have to be in the first pass. until then, the docs should be accurate.

alexmojaki · 2026-05-18T09:38:20Z

+from ..artifacts import Artifact
+from ..utils import log_internal_error
+
+# Default ceiling on bytes queued for background upload. When exceeded, `submit` blocks.


it doesn't block, it drops

should we make it drop, block, spill to disk...?

for background uploading, i think not blocking is part of the contract. i think it should spill to disk up to a higher limit, then drop.

alexmojaki · 2026-05-18T09:40:26Z

+    on the calling thread.
+    """
+
+    def __init__(self, *, base_url: str, token: str, max_queue_bytes: int = DEFAULT_MAX_QUEUE_BYTES) -> None:


max_queue_bytes isn't actually user configurable and probably should be

alexmojaki · 2026-05-18T09:43:12Z

+        # there can break the signature, so only the backend `/blob` endpoint gets auth.
+        put_headers = self._auth if target['requires_auth'] else {}
+        put = requests.request(
+            target['method'], target['url'], data=artifact.read(), headers=put_headers, timeout=_REQUEST_TIMEOUT


when the artifact is read from a file, it doesn't live in memory in the queue. but max_queue_bytes seems to be intended to save memory, so should it apply to file artifacts? in fact, what if we stored all artifacts to files to allow a bigger queue?

yeah I think it would make sense to force all artifacts to buffer on disk, they are almost by definition large

alexmojaki · 2026-05-18T09:46:42Z

    'attach_context',
    'url_from_eval',
+    'Artifact',
+    'UploadMode',


Do users need to use logfire.UploadMode? this seems like clutter in the root package.

alexmojaki · 2026-05-18T09:47:42Z

+            # Network/HTTP failures are operational, not bugs: the artifact reference is
+            # still recorded on the span, the blob just isn't stored. Best-effort upload —
+            # never crash the caller's logging call over it.
+            pass


will need retries

alexmojaki · 2026-05-18T09:50:25Z

+
+    def __init__(
+        self,
+        data: bytes,


IMO data should accept:

bytes

str, which is encoded to bytes

Path, which is like from_file

a file handle, and then from_file_handle isn't needed at all

any other object, which goes through the logfire JSON encoding

Then the constructor can handle basically anything, and from_file is only a convenience to treat str as a path instead of actual data, and to maybe save some memory depending on implementation details.

alexmojaki · 2026-05-18T09:54:19Z

+        return self._compute()[0]
+
+    @property
+    def size_bytes(self) -> int:


does the backend check that this is reported honestly?

alexmojaki · 2026-05-18T09:58:56Z

        UUID: _to_str,
        Exception: _to_str,
+        # An artifact serialises to its reference object; the blob is uploaded separately.
+        Artifact: lambda o, _: o.reference(),


we need a way to mark the contents of these as always exempt from scrubbing. this shape doesn't allow us to without adding some new machinery. if it was {'logfire.artifact': {...}} then adding logfire.artifact to the scrubber safe keys would work.

that wouldn't help if someone writes secret=Artifact(...), which will get scrubbed by default either way. not sure if we want to do something about that.

maybe we just say scrubbing doesn't apply to artifcats for now and figure it out in a followup?

i'm saying we need to figure out how to make scrubbing not apply to artifacts, right now it can. not the contents, the reference.

that seems like something we can sort out. i'm just asking if we can ship whatever falls out naturally now (even if it's kinda broken) and come up with the right apis, etc. later or if you think it needs to be bundled into this change?

i thought the goal right now was to settle on a good API? what kind of review are you looking for?

adriangb self-assigned this May 18, 2026

alexmojaki reviewed May 18, 2026

View reviewed changes

Conversation

adriangb commented May 18, 2026

What

Usage

How it works

Changes

Verification

Uh oh!

adriangb commented May 18, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented May 18, 2026

Deploying logfire-docs with Cloudflare Pages

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants