pymongoftdc

CI PyPI Python 3.10+ License: MIT

pymongoftdc reads numeric time-series metrics directly from MongoDB Full-Time Diagnostic Data Capture (FTDC) archive files.

Install

python -m pip install -e .

For development:

python -m pip install -e '.[test]'
pytest

Use

from datetime import datetime, timezone
from pyftdc import FTDCReader

reader = FTDCReader("/var/lib/mongo/diagnostic.data")
metrics = reader.get_metric(
    {"serverStatus.connections.current"},
    start=datetime(2026, 1, 1, tzinfo=timezone.utc),
    end=datetime(2026, 1, 1, 1, tzinfo=timezone.utc),
    sample_rate=0.1,
    sort_by_timestamp=False,
    workers=None,
)
points = metrics["serverStatus.connections.current"]

The source may be one metrics.* file or a directory that contains multiple metrics files.

  • Timespan endpoints are inclusive and must be timezone-aware. Omit start or end to use the earliest or latest timestamp in the source.
  • The result maps each requested name to points in source traversal order. Pass sort_by_timestamp=True to force order each point list by UTC timestamp (Usually unnecessary).
  • Pass an empty set to read every metric.
  • sample_rate must be greater than 0 and at most 1. For example, 0.1 returns approximately 10% of points. Its default is 1.0.
  • Metric chunks are decoded in separate processes. By default, workers is the detected CPU count minus one, with a minimum of one. Set workers=1 to disable multiprocessing or choose a smaller value to limit memory use.
  • query() is an alias for get_metric().
  • Use reader.get_metadata() to return the complete metadata payload from the first source file. Dedicated metadata accessors are:
    • get_mongodb_config() for the parsed getCmdLineOpts configuration
    • get_build_info() for MongoDB version and build details
    • get_host_info() for operating-system and hardware details
    • get_ulimits() for process resource limits
    • get_sys_max_open_files() for the system-wide open-file limit
    • get_metadata_start() and get_metadata_end() for collection timestamps
  • Use reader.list_metrics() to discover dotted metric paths from the first metric chunk. Pass all_chunks=True to scan the full source for schema changes.
  • A missing requested metric raises MetricNotFoundError; an invalid archive raises FTDCDecodeError.

Project layout

src/pyftdc/
  _codec.py       BSON framing and FTDC decompression
  reader.py       public query API
  models.py       returned value objects
  exceptions.py   library-specific errors
tests/             pytest tests and fixture builders

The reader supports BSON-framed type-1 metric chunks using MongoDB's delta/RLE/varint/zlib encoding. Metadata documents are safely skipped.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yaoxing from gravatar.com yaoxing

License

MIT License

Requires

Python >=3.10

Provides Extra

docs test

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pymongoftdc-0.1.1.tar.gz (16.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pymongoftdc-0.1.1-py3-none-any.whl (12.2 kB view details)

Uploaded Python 3

File details

Details for the file pymongoftdc-0.1.1.tar.gz.

File metadata

  • Download URL: pymongoftdc-0.1.1.tar.gz
  • Upload date:
  • Size: 16.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for pymongoftdc-0.1.1.tar.gz
Algorithm Hash digest
SHA256 fc253964ca3a26ad17cfb5af003c55e060cbbae9979f8b737e67bcbd9005ce98
MD5 a0f26b0717c133309bb5d5460bf7981d
BLAKE2b-256 3cacf42bd479b6895268f0477364f6ac9905048dcba14bd056a87ca2665d4722

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongoftdc-0.1.1.tar.gz:

Publisher: publish.yml on zhangyaoxing/pyftdc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pymongoftdc-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: pymongoftdc-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 12.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for pymongoftdc-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 3dd2c368bd9f7e7c6e27654fa414e832dfd5c29ca09c4308af085ffff3954895
MD5 1bfa4d47b8768a59501c2652e3c9a7c3
BLAKE2b-256 95511604793e75f4cf81dabade479a6b8330b900d3c46034ab2a51dff64b9aea

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymongoftdc-0.1.1-py3-none-any.whl:

Publisher: publish.yml on zhangyaoxing/pyftdc

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page