tracewise 0.1.0__tar.gz

tracewise-0.1.0/.dockerignore

@@ -0,0 +1,12 @@
+.git
+__pycache__
+*.pyc
+*.pyo
+.pytest_cache
+.ruff_cache
+*.egg-info
+.venv
+dist
+build
+.env
+.env.*

tracewise-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+
+# uv
+.uv/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff / linters
+.ruff_cache/
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.codex
+
+# OS
+.DS_Store
+Thumbs.db
+
+# TraceWise local data
+*.db
+*.db-shm
+*.db-wal
+.tracewise/
+/docs
+*.md
+!README.md
+!AGENTS.md
+!/docs/
+!/docs/**/*.md

tracewise-0.1.0/AGENTS.md

@@ -0,0 +1,106 @@
+# Agent Operating Contract
+
+This file is the default operating contract for agents working in this repository.
+
+## Authority
+
+- User instructions take priority.
+- This contract is otherwise strict by default.
+- An agent must not relax, skip, or reinterpret these rules on its own.
+- If an agent believes a rule should be changed for the current task, it must stop, explain the reason, and wait for explicit user permission before proceeding.
+
+## Startup Rules
+
+- Explore local project context before proposing changes or asking broad questions.
+- Read relevant files, existing docs, recent changes, and established patterns before acting.
+- Read `docs/agent-status.md` at the start of the session if it exists.
+- Do not ask questions that can be answered from the codebase or existing project files.
+- If project-specific instructions exist in additional instruction files, follow them together with this contract.
+
+## Mandatory Workflow
+
+### Feature work and behavior changes
+
+Before implementing a feature or changing behavior, the agent must:
+
+1. Explore the current project context.
+2. Write a short spec or design document. (use appropriate skills)
+3. Self-review the spec for ambiguity, contradictions, and scope issues. (use appropriate skills)
+4. Ask the user to review the spec and update it until approved.
+5. Write an implementation plan. (use appropriate skills)
+6. Self-review the plan for sequencing, scope, and verification coverage. (use appropriate skills)
+7. Ask the user to review the plan and update it until approved.
+8. Only then start implementation. (use appropriate skills)
+9. Project should be docker first. Agent tests locally, give manual steps to user to test in docker by themselves
+
+Recommended document locations:
+
+- `docs/specs/YYYY-MM-DD-<topic>.md`
+- `docs/plans/YYYY-MM-DD-<topic>.md`
+
+### Bug fixes and regressions
+
+Before fixing a bug, the agent must:
+
+1. Reproduce the issue or otherwise confirm the failure mode. (use appropriate skills)
+2. Investigate root cause before proposing a fix.
+3. Create a minimal failing test or minimal reproducible verification first, unless the user explicitly waives that requirement.
+4. Apply the smallest fix that addresses the root cause.
+
+No guessing, no stacked fixes, and no implementation before understanding the problem.
+
+### Code changes in general
+
+- Default to test-first development unless the user explicitly waives it for the current task.
+- Use the environment's formal workflows for design, planning, debugging, testing, code review, delegation, and verification when those workflows exist.
+- For larger work, break the task into isolated steps and stop after each meaningful step for user review instead of batching unrelated changes together.
+- If delegation is available, use separate workers or reviewers for independent subtasks, but keep integration and final judgment centralized.
+- never do git add, commit, push on your own. after each meaningful step completed stop with manual test steps and a commit message (feat:, chore: style), write docker test steps as well for the user to check.
+
+## Editing and Safety
+
+- State what you are about to change before editing files.
+- Follow existing project patterns before introducing new ones.
+- Do not perform unrelated refactoring while working on the current task unless the user approves it.
+- Do not revert unrelated user changes.
+- Do not use destructive commands or irreversible operations without explicit permission.
+- Do not silently change architecture, dependencies, project direction, or workflow expectations.
+
+## Verification and Review
+
+- Do not claim success without fresh verification evidence from the current session.
+- Run the smallest relevant verification that proves the change.
+- Report what was verified, what was inferred, and what was not verified in the current environment.
+- After implementation, perform an independent review pass before calling the work complete.
+- If multi-agent or reviewer support is available, use a separate reviewer for that pass when practical.
+- If asked for a review, prioritize bugs, regressions, risks, and missing verification ahead of summaries or suggestions.
+- When receiving review feedback, analyze it technically before applying it. Do not accept or reject feedback mechanically.
+
+## Communication
+
+- Keep progress updates short, direct, and factual.
+- Ask questions only when a real decision is required or the risk of assumption is high.
+- Ask one question at a time when possible.
+- Make blockers, assumptions, and tradeoffs explicit.
+- By default, do one isolated change at a time and stop for user review before moving to the next step.
+
+## Session Continuity
+
+- `docs/agent-status.md` is the persistent handoff file for this repository.
+- Read it at session start if it exists.
+- Update it after each meaningful step and before ending a session.
+- Keep it factual, compact, and current.
+- Do not rely on hidden conversation context when a durable project status can be written down.
+- If context becomes long or fragmented, prefer updating the status file over relying on memory.
+- If `docs/agent-status.md` is missing and the work is non-trivial, create it before proceeding far into the task.
+
+## Default Expectations for `docs/agent-status.md`
+
+The status file should always answer these questions:
+
+- What is the current objective?
+- What has already been done?
+- What was verified?
+- What remains pending?
+- What risks or blockers exist?
+- What is the next recommended step?

tracewise-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanmoy Sarkar Pranto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tracewise-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: tracewise
+Version: 0.1.0
+Summary: Local tracing and debugging for FastAPI apps
+Project-URL: Homepage, https://github.com/Tanmoy-Sarkar-Pranto/tracewise
+Project-URL: Repository, https://github.com/Tanmoy-Sarkar-Pranto/tracewise
+Author: Tanmoy Sarkar Pranto
+License-Expression: MIT
+License-File: LICENSE
+Keywords: debugging,fastapi,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Requires-Dist: fastapi<1.0,>=0.100.0
+Provides-Extra: dev
+Requires-Dist: anyio; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: uvicorn[standard]; extra == 'dev'
+Provides-Extra: httpx
+Requires-Dist: httpx; extra == 'httpx'
+Description-Content-Type: text/markdown
+
+# TraceWise
+
+TraceWise is a small tracing and debugging tool for FastAPI apps.
+
+It records request spans to a local SQLite database and mounts a built-in viewer
+at `/tracewise` so you can inspect traces while developing.
+
+Current scope:
+
+- inbound FastAPI request tracing
+- manual spans with `tracewise.start_span(...)`
+- decorator-based spans with `@tracewise.trace_span(...)`
+- span attributes and events
+- optional log capture
+- optional `httpx` client tracing with `traceparent` propagation
+- local SQLite storage and a minimal embedded UI
+
+This is aimed at local development and debugging. It is not trying to be a full
+APM or a hosted tracing backend.
+
+## Install
+
+For local development in this repo:
+
+```bash
+uv sync --extra dev
+```
+
+Or with `pip`:
+
+```bash
+pip install -e .
+```
+
+If you want `instrument_httpx=True`, install the optional extra:
+
+```bash
+pip install -e ".[httpx]"
+```
+
+For a published package install, the same extra would be:
+
+```bash
+pip install "tracewise[httpx]"
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+import tracewise
+
+app = FastAPI()
+
+tracewise.init(
+    app,
+    capture_logs=True,
+    instrument_httpx=True,
+)
+
+
+@app.get("/users")
+async def list_users():
+    async with tracewise.start_span("db.query", table="users", operation="SELECT"):
+        pass
+
+    tracewise.set_attribute("result.count", 2)
+    tracewise.add_event("users.loaded")
+
+    return {"users": []}
+```
+
+Once the app is running:
+
+- make a request to one of your routes
+- open `/tracewise`
+- inspect the recorded trace tree
+
+## API Surface
+
+Top-level helpers currently exposed by the package:
+
+- `tracewise.init(app, ...)`
+- `tracewise.get_current_span()`
+- `tracewise.start_span(name, **attributes)`
+- `tracewise.trace_span(name, attributes=...)`
+- `tracewise.set_attribute(key, value)`
+- `tracewise.set_attributes({...})`
+- `tracewise.add_event(name, **attributes)`
+
+Main `init()` options:
+
+- `db_path`: path to the SQLite database file
+- `max_traces`: max number of traces to keep
+- `enabled`: turn tracing on or off
+- `capture_logs`: attach a logging handler that records log events on the
+  active span
+- `instrument_httpx`: record outbound `httpx` requests and inject
+  `traceparent` headers
+
+If `db_path` is not provided, TraceWise stores data under
+`~/.tracewise/traces.db`.
+
+You can also disable tracing with:
+
+```bash
+TRACEWISE_ENABLED=false
+```
+
+## Example App
+
+A small example app lives in `tests/testapp/main.py`.
+
+To run it with Docker:
+
+```bash
+docker compose -f docker/docker-compose.yml up --build
+```
+
+Then open:
+
+- `http://localhost:8000/health`
+- `http://localhost:8000/users`
+- `http://localhost:8000/orders`
+- `http://localhost:8000/error`
+- `http://localhost:8000/tracewise`
+
+## Current Limitations
+
+- FastAPI-specific for now
+- local SQLite storage only
+- viewer UI is intentionally minimal
+- `httpx` tracing is optional and only applies if your app uses `httpx`
+- not a replacement for OpenTelemetry or a hosted tracing stack
+
+## Development
+
+Run the tests with:
+
+```bash
+uv run pytest
+```

tracewise-0.1.0/README.md

@@ -0,0 +1,142 @@
+# TraceWise
+
+TraceWise is a small tracing and debugging tool for FastAPI apps.
+
+It records request spans to a local SQLite database and mounts a built-in viewer
+at `/tracewise` so you can inspect traces while developing.
+
+Current scope:
+
+- inbound FastAPI request tracing
+- manual spans with `tracewise.start_span(...)`
+- decorator-based spans with `@tracewise.trace_span(...)`
+- span attributes and events
+- optional log capture
+- optional `httpx` client tracing with `traceparent` propagation
+- local SQLite storage and a minimal embedded UI
+
+This is aimed at local development and debugging. It is not trying to be a full
+APM or a hosted tracing backend.
+
+## Install
+
+For local development in this repo:
+
+```bash
+uv sync --extra dev
+```
+
+Or with `pip`:
+
+```bash
+pip install -e .
+```
+
+If you want `instrument_httpx=True`, install the optional extra:
+
+```bash
+pip install -e ".[httpx]"
+```
+
+For a published package install, the same extra would be:
+
+```bash
+pip install "tracewise[httpx]"
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+import tracewise
+
+app = FastAPI()
+
+tracewise.init(
+    app,
+    capture_logs=True,
+    instrument_httpx=True,
+)
+
+
+@app.get("/users")
+async def list_users():
+    async with tracewise.start_span("db.query", table="users", operation="SELECT"):
+        pass
+
+    tracewise.set_attribute("result.count", 2)
+    tracewise.add_event("users.loaded")
+
+    return {"users": []}
+```
+
+Once the app is running:
+
+- make a request to one of your routes
+- open `/tracewise`
+- inspect the recorded trace tree
+
+## API Surface
+
+Top-level helpers currently exposed by the package:
+
+- `tracewise.init(app, ...)`
+- `tracewise.get_current_span()`
+- `tracewise.start_span(name, **attributes)`
+- `tracewise.trace_span(name, attributes=...)`
+- `tracewise.set_attribute(key, value)`
+- `tracewise.set_attributes({...})`
+- `tracewise.add_event(name, **attributes)`
+
+Main `init()` options:
+
+- `db_path`: path to the SQLite database file
+- `max_traces`: max number of traces to keep
+- `enabled`: turn tracing on or off
+- `capture_logs`: attach a logging handler that records log events on the
+  active span
+- `instrument_httpx`: record outbound `httpx` requests and inject
+  `traceparent` headers
+
+If `db_path` is not provided, TraceWise stores data under
+`~/.tracewise/traces.db`.
+
+You can also disable tracing with:
+
+```bash
+TRACEWISE_ENABLED=false
+```
+
+## Example App
+
+A small example app lives in `tests/testapp/main.py`.
+
+To run it with Docker:
+
+```bash
+docker compose -f docker/docker-compose.yml up --build
+```
+
+Then open:
+
+- `http://localhost:8000/health`
+- `http://localhost:8000/users`
+- `http://localhost:8000/orders`
+- `http://localhost:8000/error`
+- `http://localhost:8000/tracewise`
+
+## Current Limitations
+
+- FastAPI-specific for now
+- local SQLite storage only
+- viewer UI is intentionally minimal
+- `httpx` tracing is optional and only applies if your app uses `httpx`
+- not a replacement for OpenTelemetry or a hosted tracing stack
+
+## Development
+
+Run the tests with:
+
+```bash
+uv run pytest
+```

tracewise-0.1.0/docker/Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.12-slim
+
+RUN pip install uv
+
+# Keep venv outside /app so the dev volume mount doesn't overwrite it
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv
+ENV UV_LINK_MODE=copy
+
+# Create non-root user, /app, and /opt/venv — all as root, then hand over
+RUN useradd -m -u 1000 appuser \
+    && mkdir -p /app /opt/venv /home/appuser/.tracewise \
+    && chown -R appuser:appuser /app /opt/venv /home/appuser
+
+USER appuser
+WORKDIR /app
+
+# Install dependencies first (without the project itself) for layer caching
+COPY --chown=appuser:appuser pyproject.toml ./
+RUN uv sync --extra dev --no-install-project
+
+# Copy source, then install the project itself
+COPY --chown=appuser:appuser . .
+RUN uv sync --extra dev
+
+EXPOSE 8000
+
+# No --reload here: use docker-compose command override for dev
+CMD ["uv", "run", "uvicorn", "tests.testapp.main:app", "--host", "0.0.0.0", "--port", "8000"]

tracewise-0.1.0/docker/docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  app:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+    ports:
+      - "127.0.0.1:8000:8000"
+    volumes:
+      - ..:/app
+      - tracewise-data:/home/appuser/.tracewise
+    environment:
+      - TRACEWISE_ENABLED=true
+    command: ["uv", "run", "uvicorn", "tests.testapp.main:app",
+              "--host", "0.0.0.0", "--port", "8000", "--reload"]
+
+volumes:
+  tracewise-data:

tracewise-0.1.0/docs/agent-status.md

@@ -0,0 +1,55 @@
+# Agent Status
+
+Update this file after each meaningful step and before ending a session.
+
+This file is the durable handoff point for future sessions. Keep it factual, compact, and current. Remove stale detail when it stops being useful.
+
+## Current Objective
+
+- Prepare TraceWise for the first real PyPI release.
+
+## Current Step
+
+- Reusable agent contract files were added. The next operational step is the real PyPI upload with a valid PyPI API token.
+
+## Done
+
+- Added project README, license, author metadata, URLs, and packaging metadata.
+- Added a real optional `httpx` extra for outbound client instrumentation.
+- Fixed `tracewise.init()` so it does not require `httpx` unless `instrument_httpx=True`.
+- Fixed `tracewise.init()` idempotency on the same FastAPI app.
+- Fixed same-app disable and re-enable behavior for `enabled=False`.
+- Verified wheel and source-distribution install paths from isolated targets under `/tmp`.
+- Verified the TestPyPI publish path with a dry run, and the user confirmed TestPyPI upload worked.
+
+## Verification
+
+- Command: `uv build --out-dir /tmp/tracewise-dist`
+  Result: built both `tracewise-0.1.0.tar.gz` and `tracewise-0.1.0-py3-none-any.whl`.
+- Command: isolated wheel and sdist smoke tests from `/tmp`
+  Result: package imported from installed artifacts, request tracing worked, and `/tracewise` mounted successfully.
+- Command: `uv publish --dry-run --trusted-publishing never --publish-url https://test.pypi.org/legacy/ --check-url https://test.pypi.org/simple/ /tmp/tracewise-dist/*`
+  Result: live TestPyPI dry run succeeded.
+- Not verified: real PyPI upload from this machine, and post-upload install smoke tests from real PyPI.
+
+## Pending
+
+- Create or export a real PyPI API token in the shell.
+- Upload the built artifacts to real PyPI.
+- Install `tracewise` from real PyPI in a clean environment and run a smoke test.
+
+## Risks or Blockers
+
+- A valid PyPI API token and 2FA-enabled PyPI account are required for the real upload.
+- PyPI filenames are immutable. If `0.1.0` is already present or a partial upload consumes the filenames, the version must be bumped before retrying.
+- If tracked packaging files change again before release, the distribution artifacts in `/tmp/tracewise-dist` should be rebuilt.
+
+## Next Recommended Step
+
+- Export `UV_PUBLISH_TOKEN` and run the real `uv publish` command against `https://upload.pypi.org/legacy/`, then verify install from PyPI.
+
+## Notes for Next Session
+
+- Read `AGENTS.md` first, then this file.
+- If the repo is not clean or if packaging files changed, rebuild artifacts before publishing.
+- After PyPI upload, verify both `tracewise` and `tracewise[httpx]` installs from PyPI in a clean environment.