Skip to main content

zharp

Zharp Application Monitoring for Python: every request traced, outgoing HTTP calls and database queries timed, logging records sent with their trace, and errors grouped into issues. Built on the official OpenTelemetry SDK — zharp only configures it (exporter, resource, propagation, the logging bridge) and turns on the instrumentations for the libraries you have.

Full documentation: zharp.io/docs/sdks/python

Install

pip install zharp

Python 3.9+.

Start it

Copy your app's key from Applications → your app → Setup in Zharp, then call init() once, before your framework starts:

import zharp

zharp.init(key="zpk_…", service="checkout-api", environment="production")
  • Django — at the top of manage.py and wsgi.py / asgi.py.
  • FastAPI / Flask — at the top of the module that creates the app, before FastAPI() / Flask(__name__).

That's all. What gets instrumented, when installed: Django, FastAPI, Flask, requests, httpx, psycopg, psycopg2, SQLAlchemy. Any other OpenTelemetry instrumentation you add is sent too.

Leave arguments out to read them from the environment: ZHARP_KEY, ZHARP_SERVICE (then OTEL_SERVICE_NAME), ZHARP_ENVIRONMENT, ZHARP_RELEASE, ZHARP_ENDPOINT. ZHARP_DISABLED=true turns it off.

Users and sessions

A browser or mobile app using a Zharp SDK sends traceparent and baggage (enduser.id, session.id) with its API calls. The request's trace continues from the front end, and every span and log of it carries the user and session — nothing to do on the server. When the server knows the user better:

zharp.set_user(id=user.id, email=user.email)   # for the rest of this request

Logs

logging is bridged: records at INFO and above (logging_level= to change, False to leave logging alone) are sent with the active trace and the request's user. Or log to Zharp directly:

zharp.log.info("Order placed", {"order_id": 42})   # debug, info, warn, error, fatal

Errors

An exception that escapes a request is reported (unhandled) with the request's trace; so is one that ends the program or a thread. Report one you caught:

try:
    charge(order)
except PaymentError as e:
    zharp.capture_error(e, {"order_id": order.id})   # handled

logger.exception(...) reports too. Each exception is reported once, even when both the instrumentation and the framework's logger see it.

Logs only

To send logs and errors without tracing:

zharp.init(key="zpk_…", service="checkout-api", tracing=False)   # or ZHARP_TRACING=false

Logs (zharp.log.* and logging), errors (uncaught and capture_error), the user, session and tags still go out. No spans are recorded or sent, HTTP clients and databases aren't instrumented, and no traceparent/baggage is added to outgoing requests. Django, FastAPI and Flask are hooked with a no-op tracer only to read the incoming traceparent and baggage, so a request's logs still carry the caller's trace id, user and session. zharp.start_span() runs its work without a span.

More

zharp.set_tag("region", "eu-west")                  # on every span and log after
with zharp.start_span("render invoice"):            # a span around some work
    render(invoice)
zharp.flush()                                       # send now: end of a job or serverless call
Option Environment Default
key ZHARP_KEY — (nothing is sent without one)
service ZHARP_SERVICE, OTEL_SERVICE_NAME name in pyproject.toml
environment ZHARP_ENVIRONMENT none
release ZHARP_RELEASE none
endpoint ZHARP_ENDPOINT https://api.zharp.io/api/v1/otlp
sample_rate ZHARP_SAMPLE_RATE 1.0 (share of traces kept; logs and handled errors always sent)
logging_level ZHARP_LOGGING_LEVEL INFO
capture_uncaught — True
instrument — True
tracing ZHARP_TRACING True (False: logs only)

Telemetry is batched and sent every 5 seconds from a background thread, gzip-compressed, and whatever is left goes when the program exits. init() never raises.

Development

python -m venv .venv && .venv/bin/pip install -e . flask fastapi httpx uvicorn
.venv/bin/python -m unittest discover -s tests

examples/fastapi_app.py and examples/crash.py run against any Zharp endpoint (set ZHARP_KEY and ZHARP_ENDPOINT).

Releasing

  1. Bump src/zharp/_version.py, update CHANGELOG.md, run the tests.
  2. rm -rf dist && python -m build (or python -c "from setuptools import build_meta as b; b.build_sdist('dist'); b.build_wheel('dist')").
  3. python -m twine upload dist/*, then tag vX.Y.Z.

License

MIT © Zharp

Metadata

Release files for zharp 0.1.0

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

Source distribution (sdist)

Source distribution for zharp 0.1.0
File Size Uploaded Provenance Actions
zharp-0.1.0.tar.gz 21.9 kB Without provenance Details for zharp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zharp 0.1.0
File Interpreter ABI Platform Actions
zharp-0.1.0-py3-none-any.whl Python 3 none any Details for zharp-0.1.0-py3-none-any.whl

Total release size: 40.8 kB

Release files / zharp-0.1.0.tar.gz

Download URL zharp-0.1.0.tar.gz
Size 21.9 kB
Tags Source
SHA-256 checksum
How to use checksums
e27868df8d11ee3f66aeb0ca3265820d7681039d86969b21f73c9f401f94059d
BLAKE2b-256 checksum
How to use checksums
0b6cd11f460a73ff2efaa13b5e31d1f7c08af8c0dc510817981cd08016066a7c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.7

Release files / zharp-0.1.0-py3-none-any.whl

Download URL zharp-0.1.0-py3-none-any.whl
Size 18.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
67c3cca2332f6016eee165f8651f87401ad879a30edab08ce888cf05e83152e1
BLAKE2b-256 checksum
How to use checksums
eb8e902b3d4e52e45064983a691b7e6c8e6a0433f3e33ce478b133917987259a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.7

Security for zharp 0.1.0

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.

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