# README.Debian I've started working on this logfire package and the python-opentelemetry-instrumentation packages because the core package is a dependency for this package logfire, which is a dep for python-mcp, which is a dep for home-assistant, which I would like to see in Debian. This is a pretty big package with lots of optional dependencies which we can add to Debian as needed and as far as maintainers step up. I will start by doing the minimum to get python-mcp updated. -- Pieter Lenaerts Sun, 18 Oct 2026 15:41:13 +0200 ## Docs Documentation is generated using mkdocs, but requires a pydantic_docs package. Pydantic has not released this package. It is not on PyPI and has no tags or releses on Github. Refer to For now I've commented out dependencies and other stuff for the docs package. ## debian/rules debian/rules follows the structure of the python-opentelemetry and python-opentelemetry-contrib source packages. The source builds two binary packages: python3-logfire from the root of the upstream source, and python3-logfire-api from the logfire-api/ subdirectory. They are listed in PYTHON_LOGFIRE_ROOT_PACKAGES and PYTHON_LOGFIRE_PACKAGES, and the dh_auto_build / dh_auto_install overrides run pybuild once per package with --name=, so it installs straight into debian/python3-. debian/py3dist-overrides maps opentelemetry-instrumentation to its binary package. It is not in the archive yet and only a Build-Depends here, so without the override dh_python3 drops it from the Depends of nocheck builds. Both builds are copied into .pybuild/dist-packages/build, which is the PYTHONPATH for the tests: some tests import logfire_api. The tests run from the source root, because they read docs/, scripts/, README.md, pyproject.toml and logfire-api/ relative to it. Of tests/otel_integrations/, only the modules listed in LOGFIRE_INTEGRATION_TESTS run. Most need the matching python3-opentelemetry-instrumentation- package from the python-opentelemetry-contrib source, or an SDK such as openai or anthropic. Some of the listed modules skip themselves when an optional SDK is missing (dspy, pydantic-ai, ...). The other modules are ignored because they need instrumentations or SDKs that are not in Debian yet, or, for test_mcp_version_detection, python3-mcp, which would make logfire and python-mcp build-depend on each other. ## Autopkgtests debian/tests/upstream-testsuite runs the same upstream test suite against the installed python3-logfire and python3-logfire-api packages, with the same ignores as debian/rules (keep both in sync). The "Testsuite: autopkgtest-pkg-python" field was dropped: it only generated a superficial "import logfire" test and could not cover logfire_api. The script copies tests/, docs/, scripts/, README.md, pyproject.toml and logfire-api/ to $AUTOPKGTEST_TMP. The tests also read files from the logfire package dir itself (docstring examples, .agents/skills), so instead of copying the sources, the script mirrors the installed package in /usr/lib/python3/dist-packages with "cp -as" (real directories, symlinked files), and mirrors the installed agent skill files (see below) to .agents/skills. That way the tests find those files and still import the installed code. Symlinked directories would not do: since Python 3.13 the "**" globs the tests use to find examples do not descend into them. The script runs the suite once per supported Python version (py3versions -s). python3-pyarrow is only built for the default version, so three tests skip themselves on the other versions; see disable_pyarrow_if_unavailable.patch below. The python3-pyarrow Build-Depends lists the architectures it is built on, so that @builddeps@ stays installable and debci can run the autopkgtest on the other architectures too (with those tests skipped). Update that list when apache-arrow adds or drops architectures (check with "rmadison -s unstable python3-pyarrow"). The Salsa CI "build i386" job is disabled in debian/salsa-ci.yml: it does a full (arch-all and arch-any) build, which needs python3-pyarrow, and that does not exist on i386. Both binary packages are Architecture: all, so the job tests nothing useful. ## Agent skill files Upstream ships instruction files for AI coding agents (SKILL.md files with references) in logfire/.agents/skills/, inside the Python package. Nothing in logfire reads them, and a dot directory in dist-packages is unusual, so debian/rules moves them to /usr/share/doc/python3-logfire/agent-skills/. They are excluded from compression, so they stay plain Markdown files: that is what agents read, and the autopkgtest reads them by name. The build-time tests use the copy in the source tree. ## Test patches Tests that cannot pass in Debian are skipped with a pytest skip mark and a specific reason, by quilt patch: at module level when a whole module is affected, otherwise per test (documentation examples per example, through pytest.param marks). A reason used more than once lives in a variable at the top of the module. * skip-git-service-version-tests.patch: tests that need the git commit hash as auto-detected service.version; there is no .git in Debian builds. * skip-tests-needing-packages-not-in-debian.patch: tests needing instrumentations or SDKs that are not packaged yet. Each reason names the missing package, so the test can be re-enabled once it is packaged. * skip-llm-cost-tests-without-genai-prices.patch: OpenAI and Anthropic tests expecting the operation.cost attribute, which logfire only sets when genai-prices is installed. They are marked with a skipif on genai_prices being importable, so packaging genai-prices re-enables them. * skip-anthropic-streamed-tool-arguments-test.patch: the anthropic SDK in Debian (1.9) is older than what upstream tests against (1.11). * disable_pyarrow_if_unavailable.patch: the three tests that call query_arrow() (test_query_arrow_read_sync/_async in test_query_client.py and test_accept_header_for_arrow_ranks_arrow_first in test_query_client_errors.py) are marked with a skipif on pyarrow being importable. python3-pyarrow is only built for the default Python version (#1146431; the apache-arrow maintainer declined to build it for all supported versions) and only on some 64-bit little-endian architectures. On the other Python versions pyarrow's Python files are present in /usr/lib/python3/dist-packages but its compiled pyarrow.lib module is not, so the check really imports pyarrow instead of using importlib.util.find_spec(). The tests run again wherever pyarrow becomes importable. pyarrow is only a test dependency: query_arrow() imports it lazily and raises ImportError when it is missing. ## Protobuf Upstream asks for protobuf >= 4.23.4, Debian has 3.21. The only incompatibility found so far is a MessageToJson() keyword in the OTLP forwarding code, which is patched (support-old-protobuf-MessageToJson.patch). ## TODO: tests that more packaging would enable Skipped or ignored tests that could run once more dependencies are in Debian. "Skipped" tests are marked in a patch and should start running by themselves (skipif) or need their mark removed; "ignored" modules have to be added to LOGFIRE_INTEGRATION_TESTS in debian/rules and debian/tests/upstream-testsuite. New Debian packages: * genai-prices (Pydantic, pure Python): about 40 OpenAI, Anthropic and Anthropic-on-Bedrock tests expecting operation.cost. They are skipped with a skipif and run as soon as genai_prices is importable. The Bedrock ones then also need python3-boto3 and python3-botocore as Build-Depends (both are in Debian). * litellm: test_logfire_api.py::test_runtime (skipped) and otel_integrations/test_litellm.py (ignored). * surrealdb SDK: three docs/integrations/databases/surrealdb.md examples (skipped) and otel_integrations/test_surrealdb.py (ignored). * pydantic-monty: the docs/integrations/monty.md example (skipped) and otel_integrations/test_monty.py (ignored). * pydantic-ai: otel_integrations/test_pydantic_ai.py (ignored) and test_pydantic_ai_mcp.py (runs, but skips itself). * dspy (plus openinference-instrumentation-dspy): test_dspy.py (runs, but skips itself). * google-genai, langchain, openai-agents, claude-agent-sdk, faststream, fastmcp, snowflake-connector-python: their otel_integrations modules (ignored). Newer versions of packages already in Debian: * anthropic >= 1.11 (Debian has 1.9): test_anthropic.py::test_streamed_tool_arguments (skipped). More python-opentelemetry-contrib binaries (the instrumented libraries are all in Debian already): * starlette, sqlite3, sqlalchemy (needs sqlite3 too), asyncpg, psycopg/psycopg2, pymongo: their otel_integrations modules (ignored). These tests need no live service. * redis, celery, mysql: their modules also need testcontainers (not in Debian) and a container runtime, so they cannot run at build time anyway. Only a Build-Depends away, probably (packages in Debian, not tried yet): * otel_integrations/test_elasticsearch.py (python3-elasticsearch) and test_litestar.py (python3-litestar). Not a packaging problem: * otel_integrations/test_mcp_version_detection.py needs python3-mcp, which would make logfire and python-mcp build-depend on each other. * skip-git-service-version-tests.patch: these tests need a git checkout. They could pass if debian/rules and the autopkgtest created a throwaway git repository before running the tests. * test_cli.py::test_inspect depends on the packages installed in upstream's development environment.