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.pyandwsgi.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
- Bump
src/zharp/_version.py, updateCHANGELOG.md, run the tests. rm -rf dist && python -m build(orpython -c "from setuptools import build_meta as b; b.build_sdist('dist'); b.build_wheel('dist')").python -m twine upload dist/*, then tagvX.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.