Skip to main content

Pilot Fish

Python Version Package Manager License

Pilot Fish is an extensible monitoring tool designed to run alongside your Python app, capturing every function call plus any custom data you choose to tap.


Overview

Most monitoring tools assume you already have the infrastructure for them: a job queue with Flower, Prometheus to collect metrics, a SQL database to store it all. For a solo hobbyist that setup is rarely worth the effort, so most small projects end up with no monitoring at all.

Pilot Fish needs none of that. Wrap your code in a with block and it runs alongside your app, recording each of your functions to a local file. You can extend it with taps; small functions you write to record your own data.

Features

  • Zero infrastructure — Impliment your monitor in less than 5 lines of code, without any pre-existing infrastructure.
  • Custom taps — Collect custom telemetry by "tapping" a function and using it within your Monitor.
  • Thread-aware — Works for multi-threaded applications on Python 3.14+, with or without the GIL.

Installation

Requires Python 3.14 or newer, regular or free-threaded.

pip install pilot-fish

or with uv:

uv add pilot-fish

Quickstart

Quick start

Without a tap

Wrap the part of your program you want to watch. Every call to your own functions is recorded to trace.jsonl.

from pilot_fish import Monitor, JsonlSink

with Monitor(JsonlSink("trace.jsonl")):
    main()

With a tap

A tap records your own data. Write a function that returns the value you care about, register it with @tap.extend, then call it through the tap anywhere in your code.

from pilot_fish import Monitor, JsonlSink, Tap

tap = Tap()

@tap.extend
def batch_size(batch):
    return len(batch)

def process(batch):
    tap.batch_size(batch)
    ...

with Monitor(JsonlSink("trace.jsonl"), tap=tap):
    process([1, 2, 3])

Each value is recorded against the call it happened in: here, 3 is attached to the process call. Outside a with Monitor(...) block, tap.batch_size(...) does nothing, so taps can stay in your code.

Call taps from inside your functions, not directly in the with block.

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Metadata

Release files for pilot-fish 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pilot-fish 0.0.1
File Size Uploaded Provenance Actions
pilot_fish-0.0.1.tar.gz 10.5 kB Without provenance Details for pilot_fish-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pilot-fish 0.0.1
File Interpreter ABI Platform Actions
pilot_fish-0.0.1-py3-none-any.whl Python 3 none any Details for pilot_fish-0.0.1-py3-none-any.whl

Total release size: 23.3 kB

Release files / pilot_fish-0.0.1.tar.gz

Download URL pilot_fish-0.0.1.tar.gz
Size 10.5 kB
Tags Source
SHA-256 checksum
How to use checksums
24ca01779a6aeda7a870e407847cc15cbbabb4e1a80bc019b2154d68ada7f5b0
BLAKE2b-256 checksum
How to use checksums
19e1c4f2a2718a43099731d98c69831cb6f144754940572c43516de1f11c6203
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / pilot_fish-0.0.1-py3-none-any.whl

Download URL pilot_fish-0.0.1-py3-none-any.whl
Size 12.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8794ae4c8a131c3ed33823ef0ceed228112b6f228230595c1f745c7027935a99
BLAKE2b-256 checksum
How to use checksums
a41a55020cc9b1484e11b9e39bebd36cae1362a08f0150bc285a521d6ebe9c76
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.16 {"installer":{"name":"uv","version":"0.11.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for pilot-fish 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page