daniel156161
bc44273155
Build and Push Docker Container / build-and-push (push) Successful in 1m34s
- Add opt-in OTLP/HTTP export with bounded background batching. - Propagate W3C context and correlate wide events with response trace IDs. - Update my_helpers for Convex child spans and native request IDs. - Respect parent sampling and shut down the exporter off the event loop. - Keep raw URLs, payloads and exception text out of spans. - Cover worker isolation, retries, sampling, privacy and exporter lifecycle. - Document collector configuration and bump NanoShare to 1.27.5. - Refresh locked dependencies, including pytest and watchdog. - Validate the changes with 293 passing tests.
75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# NanoShare
|
|
Quart-based file sharing service with a desktop CLI and folder sync client.
|
|
|
|
## Python versions
|
|
- **Server: Python 3.15+**, matching the `quart_common` submodule's minimum.
|
|
`.python-version` and the Docker image select Python 3.15.
|
|
- **Standalone CLI: Python 3.14+**. Install with `uv tool install ./cli`.
|
|
|
|
## Modern Python features
|
|
- Native deferred annotations (Python 3.14, PEP 649/749) replace
|
|
`from __future__ import annotations` in application and CLI modules.
|
|
- The CLI uses Python 3.14's `argparse` command typo suggestions.
|
|
- Targeted `__lazy_modules__` declarations (Python 3.15, PEP 810) defer
|
|
command-specific CLI dependencies and QR/Pillow imports until needed.
|
|
Python 3.14 imports these normally. Server registration imports remain eager;
|
|
do not enable global lazy imports for the application.
|
|
|
|
## OpenTelemetry request tracing
|
|
Tracing follows the setup in **My Webside and API** and is disabled unless an
|
|
OTLP endpoint is configured. Export uses OTLP/HTTP protobuf with a bounded
|
|
background queue (2-second export timeout), not network I/O on the request path.
|
|
|
|
Example environment variables (also usable with Docker):
|
|
```dotenv
|
|
OTEL_SERVICE_NAME=nanoshare
|
|
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
|
|
OTEL_TRACES_SAMPLER_ARG=0.1
|
|
```
|
|
|
|
| Variable | Purpose |
|
|
| --- | --- |
|
|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Collector base URL; exporter appends `/v1/traces`. |
|
|
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Full trace URL; takes precedence over the base URL. |
|
|
| `OTEL_SERVICE_NAME` | Service resource name; falls back to `SERVICE_NAME`, then `nanoshare`. |
|
|
| `OTEL_TRACES_SAMPLER_ARG` | Root-request sampling ratio from `0` to `1`, default `0.1`. Valid parent sampling decisions are respected. |
|
|
| `OTEL_EXPORTER_OTLP_HEADERS` | Optional exporter authentication headers; use environment secrets, never commit credentials. |
|
|
| `OTEL_EXPORTER_OTLP_TRACES_HEADERS` | Optional trace-specific exporter headers. |
|
|
|
|
HTTP server spans accept W3C `traceparent`/`tracestate`, return `X-Trace-ID`, and
|
|
correlate existing wide-event logs through `trace_id` and `request.id`. Route
|
|
names use templates rather than actual file IDs or paths. The existing
|
|
`my_helpers` Convex worker instrumentation creates child client spans across
|
|
worker/thread boundaries, propagates W3C context, and sends native
|
|
`convex-request-id: otel-<trace-id>-<span-id>` headers without changing function
|
|
arguments. Retries get distinct span/request IDs.
|
|
|
|
Spans do **not** capture payloads, query strings, raw URLs, cookies, credentials,
|
|
or exception text. WebSockets and ASGI lifespan messages pass through unchanged.
|
|
This integration exports **traces only**, not OTel metrics or logs; existing
|
|
wide-event logging remains independent. The SDK shuts down its exporter off the
|
|
event loop during application shutdown. Configure the collector/network outside
|
|
this project; no collector container is added here.
|
|
|
|
## Development and tests
|
|
```bash
|
|
uv sync --locked
|
|
uv run --locked python -m pytest -q
|
|
```
|
|
|
|
The dev dependency group includes pytest, pytest-asyncio, and watchdog.
|
|
The Docker build excludes this group with `--no-dev`.
|
|
|
|
The complete suite includes `quart_common/tests` and requires Python 3.15.
|
|
For standalone CLI checks on Python 3.14, use a separate environment:
|
|
|
|
```bash
|
|
uv venv --python 3.14 /tmp/nanoshare-cli-py314
|
|
uv pip install --python /tmp/nanoshare-cli-py314/bin/python ./cli pytest
|
|
/tmp/nanoshare-cli-py314/bin/python -m pytest -q tests/test_nanoshare_cli.py
|
|
```
|
|
|
|
Regression tests in `tests/test_python_features.py` cover deferred annotations,
|
|
command suggestions, lazy help/completion imports, and QR rendering. Lazy import
|
|
checks are skipped on Python 3.14.
|