Skip to main content

jstverify-tracing

Python distributed tracing SDK for JstVerify application mapping. Auto-instruments your backend to produce trace spans that connect with the JstVerify JavaScript SDK, giving you a full frontend-to-backend service map.

Installation

pip install jstverify-tracing

With framework extras:

pip install jstverify-tracing[flask]
pip install jstverify-tracing[django]
pip install jstverify-tracing[fastapi]

Quick Start

1. Initialize (once at startup)

import jstverify_tracing

jstverify_tracing.init(
    api_key="your-sdk-key",
    service_name="my-backend",
)

The endpoint defaults to the production ingestion URL (https://sdkapi.jstverify.com/v1/tracing/spans). Override for dev environments:

jstverify_tracing.init(
    api_key="your-sdk-key",
    endpoint="https://sdkapi.dev.jstverify.com/v1/tracing/spans",
    service_name="my-backend",
)

2. Add Framework Middleware

Flask:

from jstverify_tracing.integrations.flask import JstVerifyTracingMiddleware
JstVerifyTracingMiddleware(app)

Django (settings.py):

MIDDLEWARE = [
    "jstverify_tracing.integrations.django.JstVerifyTracingMiddleware",
    ...
]

FastAPI:

from jstverify_tracing.integrations.fastapi import JstVerifyTracingMiddleware
app.add_middleware(JstVerifyTracingMiddleware)

AWS Lambda (API Gateway):

from jstverify_tracing.integrations.awslambda import JstVerifyTracingMiddleware

@JstVerifyTracingMiddleware
def lambda_handler(event, context):
    return {"statusCode": 200, "body": "ok"}

Flask / Django on AWS Lambda (via apig_wsgi, Mangum, etc.):

When running a framework app on Lambda, use the framework middleware above for tracing — but you must also call jstverify_tracing.flush() at the end of each invocation. The framework middleware buffers spans for a background flush thread, but Lambda freezes the process between invocations so that thread never runs.

# handler.py (Flask + apig_wsgi example)
from apig_wsgi import make_lambda_handler
from app import app
import jstverify_tracing

_apig_handler = make_lambda_handler(app)

def handler(event, context):
    try:
        return _apig_handler(event, context)
    finally:
        jstverify_tracing.flush()
# handler.py (Django + Mangum example)
from mangum import Mangum
from myapp.asgi import application
import jstverify_tracing

_mangum_handler = Mangum(application, lifespan="off")

def handler(event, context):
    try:
        return _mangum_handler(event, context)
    finally:
        jstverify_tracing.flush()

Note: The @JstVerifyTracingMiddleware Lambda decorator (below) handles flushing automatically — this manual flush is only needed when using framework middleware on Lambda.

AWS AppSync Lambda Resolver:

from jstverify_tracing.integrations.appsync import JstVerifyAppSyncMiddleware

@JstVerifyAppSyncMiddleware
def handler(event, context):
    return [{"id": "1", "name": "Alice"}]

The AppSync middleware extracts trace context from event["request"]["headers"] and derives the operation name from event["info"]["parentTypeName"] and event["info"]["fieldName"] (e.g. Query.listUsers). Only direct transport mode is supported — relay mode is not available for AppSync since GraphQL responses cannot carry custom HTTP headers.

3. Manual Instrumentation (optional)

from jstverify_tracing import trace, trace_span

@trace("process-payment")
def process_payment(order_id):
    ...

def handle_order(order_id):
    with trace_span("validate-order") as span:
        ...
        span.set_status(200)
    with trace_span("charge-card") as span:
        ...
        span.set_http_metadata(method="POST", url="/payments/charge", status_code=201)

4. Custom Attributes

Attach custom key-value metadata to any span. Values are coerced to strings.

Via @trace decorator:

@trace("process-payment", attributes={"env": "prod", "retries": 3})
def process_payment(order_id):
    ...

Via SpanHandle.set_attribute():

with trace_span("validate-order") as span:
    span.set_attribute("orderId", order_id)
    span.set_attribute("itemCount", len(items))
    ...

When both options and handle set the same key, the handle value wins.

5. DynamoDB Tracing

The patch_requests=True option only patches the requests HTTP library. AWS SDK calls via boto3 use urllib3 directly, so DynamoDB, S3, and SQS operations are not auto-traced.

Use the trace_dynamodb() helper to wrap individual DynamoDB operations:

from jstverify_tracing import trace_dynamodb

# Instead of: table.get_item(Key={"UserID": "123"})
result = trace_dynamodb("GetItem", table, Key={"UserID": "123"})

# Works with any DynamoDB operation
result = trace_dynamodb("Query", table, KeyConditionExpression="pk = :pk",
                        ExpressionAttributeValues={":pk": org_id})
result = trace_dynamodb("PutItem", table, Item={"UserID": "456", "name": "Alice"})

Each call creates a child span with the operation name (e.g. DynamoDB.GetItem) and the table name in metadata.

6. Shutdown

jstverify_tracing.shutdown()

Shutdown is also registered via atexit automatically.

Configuration Options

Parameter Type Default Description
api_key str required Your JstVerify SDK API key
endpoint str production URL Span ingestion endpoint URL (defaults to https://sdkapi.jstverify.com/v1/tracing/spans)
service_name str required Service name shown in the service map
service_type str "http" Service type identifier
transport str "direct" "direct" sends spans via HTTP; "relay" encodes spans into response headers
flush_interval float 5.0 Seconds between background flushes
max_queue_size int 200 Max buffered spans (circular buffer)
max_batch_size int 50 Max spans per API request
debug bool False Enable debug logging
patch_requests bool True Auto-patch requests library for outgoing HTTP tracing

How It Works

Direct Mode (default)

  1. The middleware reads X-JstVerify-Trace-Id and X-JstVerify-Parent-Span-Id headers from incoming requests (injected by the JS SDK).
  2. A root span is created for each request, with nested child spans for @trace decorated functions and trace_span context managers.
  3. Outgoing requests library calls are automatically instrumented — trace headers are injected so downstream services can continue the trace.
  4. Spans are buffered in a thread-safe queue and flushed to the JstVerify API in batches by a background daemon thread.

Relay Mode

For backends without outbound internet access (private VPC, strict firewalls), relay mode encodes spans into the X-JstVerify-Spans response header. The JstVerify JS SDK reads this header and relays the spans to the ingestion API on behalf of the backend.

jstverify_tracing.init(
    api_key="your-sdk-key",
    service_name="my-backend",
    transport="relay",  # No endpoint needed
)

How it works:

  1. Each request collects spans in a per-request buffer (async-safe via contextvars).
  2. When the response is sent, all spans are base64url-encoded into the X-JstVerify-Spans header.
  3. The JS SDK decodes the header and merges the spans into its own flush queue.

Limitations:

  • ~20-30 spans per response max due to the 7500-byte header size limit.
  • Only works for request-response flows — async background jobs have no response to carry spans.
  • Cross-origin requests require the Access-Control-Expose-Headers header (set automatically by the middleware).

License

MIT

Metadata

Release files for jstverify-tracing 0.14.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 jstverify-tracing 0.14.0
File Size Uploaded Provenance Actions
jstverify_tracing-0.14.0.tar.gz 43.9 kB Without provenance Details for jstverify_tracing-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jstverify-tracing 0.14.0
File Interpreter ABI Platform Actions
jstverify_tracing-0.14.0-py3-none-any.whl Python 3 none any Details for jstverify_tracing-0.14.0-py3-none-any.whl

Total release size: 82.9 kB

Release files / jstverify_tracing-0.14.0.tar.gz

Download URL jstverify_tracing-0.14.0.tar.gz
Size 43.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d6d461a14b04726659ba27eac7f5281cea7df920d27676421ac147b264782839
BLAKE2b-256 checksum
How to use checksums
6e3cecdcf26b15187625b2a53b3aebe18d57614e3041c5958d57dc288cd535c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / jstverify_tracing-0.14.0-py3-none-any.whl

Download URL jstverify_tracing-0.14.0-py3-none-any.whl
Size 38.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fc515a8e3c3e160b76cc341c65b3826567e1eeeece6ae377f85279f54121b13
BLAKE2b-256 checksum
How to use checksums
703310cebe10450f134dcbab8970a59fe55886e2fd9c460ef6952a3cb33f0296
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for jstverify-tracing 0.14.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.

Release history Release notifications | RSS feed

This release

0.14.0 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