netflix-spectator-py is a stateless, stdlib-only Python thin client that turns meter updates into SpectatorD protocol lines and sends them (UDP, Unix socket, file, or memory) to SpectatorD, which aggregates and publishes to Atlas.
- Setup and releases: README.md.
- User docs live on the Atlas site, not in this repo: https://netflix.github.io/atlas-docs/spectator/lang/py/usage/
- Protocol reference: https://netflix.github.io/atlas-docs/spectator/agent/usage/
| Task | Command |
|---|---|
| Create venv + dev deps | make setup-venv (creates ./venv, runs pip install -e ".[dev]") |
| Test + coverage | make test → pytest --cov=spectator tests |
| Single test | venv/bin/pytest tests/meter/test_counter.py::CounterTest::test_increment |
| Lint + format check | make lint → ruff check . and ruff format --check . |
| Auto-fix + format | make format → ruff check --fix . and ruff format . |
| Type check | make typecheck → mypy spectator tests |
| Packaging check | make check-manifest (check-manifest, python -m build, twine check --strict dist/*) |
| Full CI gate | make all (clean, test, lint, typecheck, check-manifest) |
| Coverage report | make coverage (opens htmlcov/index.html on macOS) |
| Benchmark | make benchmark BASELINE=main (times one meter update in the working tree next to a git revision; CANDIDATE=<revision> replaces the working tree) |
| Build dist | python -m build --sdist --wheel --outdir dist/ . |
| Clean | make clean |
| Migrations | None. No database or schema. |
- On macOS, every make target sources
venv/bin/activate. Runmake setup-venvfirst or the targets fail. On Linux they use the ambient Python. - CI (
.github/workflows/pr.yml) runsmake install-deps && make allon Python 3.10, 3.11, 3.12 and 3.13. - Baseline is clean: ruff check and ruff format report nothing, mypy reports no issues, all tests pass. Keep it that way.
make benchmarkis not part ofmake allor CI, because its timings depend on the machine. For a performance change, runmake benchmark BASELINE=mainand quote the table in the PR.- All packaging and tool config (ruff, mypy, pytest, check-manifest) lives in
pyproject.toml. There is nosetup.pyorsetup.cfg. - Release: follow "Releasing" in
README.md. Merge theversionbump inpyproject.tomlbefore creating thevX.Y.Zrelease. A tag on a commit with a different version fails to publish; this is why 1.2.0 never reached PyPI.release.ymlnow checks the tag against thepyproject.tomlversion (PEP 440, sov1.3.0-rc.1matches1.3.0rc1) before building. Never createv*tags or releases unless you are releasing.
spectator/
__init__.py Public API: re-exports every public class + deprecated GlobalRegistry
config.py Config(location, extra_common_tags, buffer_size, is_global) + env overrides
common_tags.py nf.container / nf.process from env; tag validation
registry.py Registry: two factory methods per meter type
protocol_parser.py Symbol -> meter class map; line parser (testing utility)
stopwatch.py StopWatch context manager -> Timer / PercentileTimer
clock.py SystemClock (perf_counter), ManualClock (tests)
meter/ One meter class per file; all subclass Meter
meter_id.py MeterId: name + tags -> sanitized, sorted spectatord_id
writer/ Writer ABC (write, close) + implementations
new_writer.py location -> writer factory; WriterUnion
socket_writer.py UDP/Unix datagram writer, optional LineBuffer + flush thread
line_buffer.py Byte-sized line batching
tests/ Mirrors package layout; udp_server.py / unix_server.py helpers
benchmarks/ update_cost.py: times one meter update, side by side with a git revision
Data flow: Registry.counter(name, tags) → MeterId (+ extra common tags) → Counter(id, writer) → writer.write("c:<id>:<value>"). Nothing is aggregated in-process; SpectatorD does that.
- Python ≥ 3.10. Use built-in generics and PEP 604 unions (
dict[str, str],list[str],X | None), andtyping.TypeAliasfor aliases. Never useOptional,Dict,ListorUnion; ruff'sUPrules reject them. No 3.11+ features (typing.Self,except*,tomllib, thetypestatement). - Formatting is
ruff format(Black style, 88 columns). Runmake formatbefore committing and never hand-format. Long strings, comments and docstrings are allowed (E501 is off). - ruff is pinned in
pyproject.toml(ruff==X.Y.Z). To upgrade: bump the pin, runmake format, commit any reformat on its own, and add that commit's full hash to.git-blame-ignore-revs. Never mix a reformat with other changes. - Add a
# noqa: <code>only when the rule is genuinely wrong for that line. Existing ones:B024onClock/Meter,SIM115on theFileWriterfile handle. - Type-annotate every signature, including
-> None. mypy checkstests/too, against Python 3.10. The package shipspy.typed. - Runtime is stdlib-only (no
dependencies). Never add a runtime dependency. Dev tools go inpyproject.toml→[project.optional-dependencies] dev. - Logging:
self._logger = logging.getLogger(__name__). Pass lazy%sargs, never f-strings, to log calls. Log at info on construction, debug per write, error on I/O failure. GlobalRegistry paths (config.is_global) log at debug. - Build protocol lines with f-strings:
f"{self._meter_type_symbol}:{self._id.spectatord_id}:{value}". - Never raise from instrumentation calls (
increment,record,set,write). Drop bad input, optionally with awarning. Writers catchOSErrorand log it. OnlyConfigraises (ValueErroron an invalid location). - Defaults: use
X | None = Noneand build the object inside the function. Never use mutable or object default args. - Registry pattern: each meter gets
<type>(name, tags=None)and<type>_with_id(meter_id). - Every meter class has a docstring explaining its Atlas semantics. ruff doesn't enforce this; keep doing it anyway.
- Commit subjects are short and imperative with the PR number:
Fix LineBuffer payload byte accounting (#98).
spectator/meter/<name>.py: subclassMeter, defaultwritertoNone(Metersubstitutes aNoopWriter), pass the SpectatorD symbol tosuper().__init__.- Add both factory methods to
Registry. - Register the symbol in
protocol_parser._METER_CLASSES. - Import it in
spectator/__init__.pyand add it to__all__. - Add
tests/meter/test_<name>.py, plus cases intests/test_registry.pyandtests/test_protocol_parser.py.
Subclass Writer. Add it to WriterUnion and new_writer, add the location to Config.is_valid_output_location, and document it in the Config docstring.
- Write
unittest.TestCaseclasses; pytest runs them. Import from top-levelspectator, and import helpers relatively (from ..udp_server import UdpServer). - Assert exact protocol lines: use
Registry(Config("memory"))orCounter(id, MemoryWriter()), thenwriter().last_line(). - Socket tests: wrap
UdpServer()(ephemeral port) orUnixServer()incontextlib.closing. - Env vars: use
patch.dict(os.environ, {...}). Never leave the env mutated. - Time: use
ManualClock, neversleep. - Every bug fix ships with a regression test.
GlobalRegistryis built atimport spectator. Its env vars (SPECTATOR_OUTPUT_LOCATION,NETFLIX_CONTAINER_NAME,TITUS_CONTAINER_NAME,NETFLIX_PROCESS_NAME) must be set before the first import.Registry()reads the env when it is constructed (#96). Never reintroduceconfig: Config = Config(), because that default is evaluated once at import. The sentence in theConfigdocstring sayingRegistry()reads config at import is stale.tests/conftest.pystrips theNETFLIX_*/TITUS_*env vars before any test importsspectator. Keep global env scrubbing there.SocketWriteropens its socket lazily on the firstwrite(), soimport spectatornever opens a socket. Keep it lazy.
SPECTATOR_OUTPUT_LOCATIONoverrides any location passed in code, includingConfig("memory")in tests. Unset it in your shell before running tests.- The env-derived
nf.container/nf.processtags overrideextra_common_tagskeys with the same name. new_writermutatesconfig.location:"udp"becomesudp://127.0.0.1:1234and"unix"becomesunix:///run/spectatord/spectatord.unix.- Match locations by scheme prefix (
startswith("udp://")), never by substring. A Unix path containingudpwas once misrouted (#93). file://paths are percent-decoded withunquote(#97).- A
MeterId(...)built directly skips extra common tags. UseRegistry.new_id(). The*_with_id()methods do not add common tags. Registry.new_id()builds theMeterIdonce, from the caller's tags merged with the extra common tags. Never go back toMeterId(name, tags).with_tags(...)on that path; it builds every id twice.
SocketWriter._lockis anRLockso thatclose()called from a signal handler cannot deadlock. Never change it to aLock.close()sets_closed, flushes the buffer, then closes the socket infinally(#95). Writes afterclose()are no-ops.buffer_size > 0starts a daemon thread that flushes every 5 s. In pre-fork servers (gunicorn, multiprocessing), create buffered Registries after the fork.LineBuffercounts UTF-8 bytes plus the\nseparators (#98). Never size it withlen(str)for non-ASCII text.FileWriter.close()only flushes stdout/stderr and must never close them (#94).MemoryWriter.close()clears the captured lines, so assert before closing.- Writers catch only
OSError. Anything else, such as aUnicodeEncodeErrorfrom lone surrogates, propagates to the caller.
- The type symbols (
c C U g m A t T d D S) and thesymbol:id:valueline format are a protocol contract. Changing them breaks ingestion. MeterIdreplaces characters outside[-._A-Za-z0-9~^]with_, drops non-str or empty tag keys/values with a warning, and sorts tags inspectatord_id. Expected strings in tests must list tags in sorted order.Counter.incrementsilently dropsdelta <= 0. Timers and distribution summaries silently drop negative values.Gauge(ttl_seconds=N)emits the symbolg,N. The default TTL is 900 s; SpectatorD enforces a minimum of 5 s.MonotonicCounterUint.set()takes actypes.c_uint64, not anint.- Time code blocks with
with StopWatch(timer):. There is notimer.stopwatch()method, despite what thePercentileTimerdocstring says. DistinctCountSketchencoding must stay byte-identical to the other Spectator clients: UTF-8 witherrors="replace", 8-byte little-endian ints,boolrejected, then base64.- Percentile timers and summaries (up to 300× the cost) and
DistinctCountSketchneed low, bounded tag cardinality. Never use IDs or raw user input as tag values.
tests/test_global_registry.pybinds UDP127.0.0.1:1234, the default SpectatorD port, so it fails if a localspectatordis running.
- Packages are auto-discovered (
include = ["spectator*"]).py.typedships through[tool.setuptools.package-data]; a non-.pyfile needed at runtime must be added there too. - Add any non-
.pyfile underspectator/toMANIFEST.inorcheck-manifestfails. New top-level repo-only files (docs, configs) go in[tool.check-manifest] ignoreinpyproject.tomlinstead. __all__inspectator/__init__.pydefines the public API, so renaming or removing a name is a breaking change.GlobalRegistryis deprecated but must keep working.- Secrets: automated releases use the
PYPI_API_TOKENGitHub Actions secret, and manual releases use a maintainer's local~/.pypircor twine credentials. Never commit~/.pypirc, tokens,dist/orvenv/.