Stem Docs

Bandwidth File

Bandwidth File

Parsing for Bandwidth Authority metrics as described in Tor's bandwidth-file-spec.

Module Overview:

BandwidthFile - Tor bandwidth authority measurements.

New in version 1.8.0.

class stem.descriptor.bandwidth_file.RecentStats[source]

Bases: object

Statistical information collected over the last 'data_period' (by default five days).

Variables:
  • consensus_count (int) -- number of consensuses published during this period
  • prioritized_relays (int) -- number of relays prioritized to be measured
  • prioritized_relay_lists (int) -- number of times a set of relays were prioritized to be measured
  • measurement_attempts (int) -- number of relay measurements we attempted
  • measurement_failures (int) -- number of measurement attempts that failed
  • relay_failures (RelayFailures) -- number of relays we failed to measure
class stem.descriptor.bandwidth_file.RelayFailures[source]

Bases: object

Summary of the number of relays we were unable to measure.

Variables:
  • no_measurement (int) -- number of relays that did not have any successful measurements
  • insuffient_period (int) -- number of relays whos measurements were collected over a period that was too small (1 day by default)
  • insufficient_measurements (int) -- number of relays we did not collect enough measurements for (2 by default)
  • stale (int) -- number of relays whos latest measurement is too old (5 days by default)
class stem.descriptor.bandwidth_file.BandwidthFile(raw_content, validate=False)[source]

Bases: stem.descriptor.Descriptor

Tor bandwidth authority measurements.

Variables:
  • measurements (dict) -- * mapping of relay fingerprints to their bandwidth measurement metadata
  • header (dict) -- * header metadata
  • timestamp (datetime) -- * time when these metrics were published
  • version (str) -- * document format version
  • software (str) -- application that generated these metrics
  • software_version (str) -- version of the application that generated these metrics
  • earliest_bandwidth (datetime) -- time of the first sampling
  • latest_bandwidth (datetime) -- time of the last sampling
  • created_at (datetime) -- time when this file was created
  • generated_at (datetime) -- time when collection of these metrics started
  • consensus_size (int) -- number of relays in the consensus
  • eligible_count (int) -- relays with enough measurements to be included
  • eligible_percent (int) -- percentage of consensus with enough measurements
  • min_count (int) -- minimum eligible relays for results to be provided
  • min_percent (int) -- minimum measured percentage of the consensus
  • scanner_country (str) -- country code where this scan took place
  • destinations_countries (list) -- all country codes that were scanned
  • time_to_report_half_network (int) -- estimated number of seconds required to measure half the network, given recent measurements
  • recent_stats (RecentStats) -- statistical information collected over the last 'data_period' (by default five days)

* attribute is either required when we're parsed with validation or has a default value, others are left as None if undefined

TYPE_ANNOTATION_NAME = 'bandwidth-file'
classmethod content(attr=None, exclude=(), sign=False)[source]

Creates descriptor content with the given attributes. This descriptor type differs somewhat from others and treats our attr/exclude attributes as follows...

  • 'timestamp' is a reserved key for our mandatory header unix timestamp.
  • 'content' is a reserved key for our bandwidth measurement lines.
  • All other keys are treated as header fields.

For example...

BandwidthFile.content({
  'timestamp': '12345',
  'version': '1.2.0',
  'content': [],
})
k = 'latest_bandwidth'