pip_services3_components.count package

Submodules

Module contents

pip_services3_components.count.__init__

Performance counters. They show non-functional characteristics about how the code works, like: times called, response time, objects saved/processed. Using these numbers, we can show how the code works in the system – how stable, fast, expandable it is.

copyright

Conceptual Vision Consulting LLC 2018-2019, see AUTHORS for more details.

license

MIT, see LICENSE for more details.

class pip_services3_components.count.CachedCounters

Bases: pip_services3_components.count.ICounters.ICounters, pip_services3_commons.config.IReconfigurable.IReconfigurable, pip_services3_components.count.ICounterTimingCallback.ICounterTimingCallback

Abstract implementation of performance counters that measures and stores counters in memory. Child classes implement saving of the counters into various destinations.

### Configuration parameters ###
  • options:

    • interval: interval in milliseconds to save current counters measurements (default: 5 mins)

    • reset_timeout: timeout in milliseconds to reset the counters. 0 disables the reset (default: 0)

begin_timing(name: str) → pip_services3_components.count.CounterTiming.CounterTiming

Begins measurement of execution time interval. It returns CounterTiming object which has to be called at CounterTiming.end_timing() to end the measurement and update the counter.

Parameters

name – a counter name of Interval type.

Returns

a CounterTiming callback object to end timing.

clear(name: str)

Clears (resets) a counter specified by its name.

Parameters

name – a counter name to clear.

clear_all()

Clears (resets) all counters.

configure(config: pip_services3_commons.config.ConfigParams.ConfigParams)

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

dump()

Dumps (saves) the current values of counters.

end_timing(name: str, elapsed: float)

Ends measurement of execution elapsed time and updates specified counter.

Parameters

  • name – a counter name

  • elapsed – execution elapsed time in milliseconds to update the counter.

get(name: str, typ: pip_services3_components.count.CounterType.CounterType) → pip_services3_components.count.Counter.Counter

Gets a counter specified by its name. It counter does not exist or its type doesn’t match the specified type it creates a new one.

Parameters

  • name – a counter name to retrieve.

  • typ – a counter type.

Returns

an existing or newly created counter of the specified type.

get_all() → List[pip_services3_components.count.Counter.Counter]

Gets all captured counters.

Returns

a list with counters.

get_interval() → float

Gets the counters dump/save interval.

Returns

the interval in milliseconds.

increment(name: str, value: float)

Increments counter by given value.

Parameters

  • name – a counter name of Increment type.

  • value – a value to add to the counter.

increment_one(name: str)

Increments counter by 1.

Parameters

name – a counter name of Increment type.

last(name: str, value: float)

Records the last calculated measurement value. Usually this method is used by metrics calculated externally.

Parameters

  • name – a counter name of Last type.

  • value – a last value to record.

set_interval(value: float)

Sets the counters dump/save interval.

Parameters

value – a new interval in milliseconds.

stats(name: str, value: float)

Calculates min/average/max statistics based on the current and previous values.

Parameters

  • name – a counter name of Statistics type

  • value – a value to update statistics

timestamp(name: str, value: datetime.datetime)

Records the given timestamp.

Parameters

  • name – a counter name of Timestamp type.

  • value – a timestamp to record.

timestamp_now(name: str)

Records the current time as a timestamp.

Parameters

name – a counter name of Timestamp type.

class pip_services3_components.count.CompositeCounters(references: pip_services3_commons.refer.IReferences.IReferences = None)

Bases: pip_services3_components.count.ICounters.ICounters, pip_services3_components.count.ICounterTimingCallback.ICounterTimingCallback, pip_services3_commons.refer.IReferenceable.IReferenceable

Aggregates all counters from component references under a single component.

It allows to capture metrics and conveniently send them to multiple destinations.

### References ###

  • *:counters:*:*:1.0 (optional) ICounters components to pass collected measurements

Example:

class MyComponent(IReferenceable):
    _counters = CompositeCounters()

def set_references(self, references):
    self._counters.set_references(references)

def my_method(self):
    self._counters.increment("mycomponent.mymethod.calls")
    timing = this._counters.begin_timing("mycomponent.mymethod.exec_time")
    # do something

    timing.end_timing()
begin_timing(name: str) → pip_services3_components.count.CounterTiming.CounterTiming

Begins measurement of execution time interval. It returns CounterTiming object which has to be called at CounterTiming.end_timing() to end the measurement and update the counter.

Parameters

name – a counter name of Interval type.

Returns

a CounterTiming callback object to end timing.

end_timing(name: str, elapsed: float)

Ends measurement of execution elapsed time and updates specified counter.

Parameters

  • name – a counter name

  • elapsed – execution elapsed time in milliseconds to update the counter.

See CounterTiming.end_timing()

increment(name: str, value: float)

Increments counter by given value.

Parameters

  • name – a counter name of Increment type.

  • value – a value to add to the counter.

increment_one(name: str)

Increments counter by 1.

Parameters

name – a counter name of Increment type.

last(name: str, value: float)

Records the last calculated measurement value. Usually this method is used by metrics calculated externally.

Parameters

  • name – a counter name of Last type.

  • value – a last value to record.

set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

stats(name: str, value: float)

Calculates min/average/max statistics based on the current and previous values.

Parameters

  • name – a counter name of Statistics type

  • value – a value to update statistics

timestamp(name: str, value: datetime.datetime)

Records the given timestamp.

Parameters

  • name – a counter name of Timestamp type.

  • value – a timestamp to record.

timestamp_now(name: str)

Records the current time as a timestamp.

Parameters

name – a counter name of Timestamp type.

class pip_services3_components.count.Counter(name: str = None, tipe: <module 'pip_services3_components.count.CounterType' from '/pip_services3_components/count/CounterType.py'> = None)

Bases: object

Data object to store measurement for a performance counter. This object is used by CachedCounters to store counters.

class pip_services3_components.count.CounterTiming(counter: str = None, callback: <module 'pip_services3_components.count.ICounterTimingCallback' from '/pip_services3_components/count/ICounterTimingCallback.py'> = None)

Bases: object

Callback object returned by pip_services3_components.count.ICounters.ICounters.begin_timing() to end timing of execution block and update the associated counter.

Example:

timing = counters.begin_timing(“mymethod.exec_time”) # do something timing.end_timing()

end_timing()

Ends timing of an execution block, calculates elapsed time and updates the associated counter.

class pip_services3_components.count.CounterType(value)

Bases: enum.Enum

Types of counters that measure different types of metrics

Increment = 4
Interval = 0
LastValue = 1
Statistics = 2
Timestamp = 3
static to_string(typ)
class pip_services3_components.count.DefaultCountersFactory

Bases: pip_services3_components.build.Factory.Factory

Creates ICounters components by their descriptors.

See Factory, NullCounters, LogCounters, CompositeCounters

CompositeCountersDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
LogCountersDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
NullCountersDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>
class pip_services3_components.count.ICounterTimingCallback

Bases: abc.ABC

Interface for a callback to end measurement of execution elapsed time.

See CounterTiming

end_timing(name: str, elapsed: float)

Ends measurement of execution elapsed time and updates specified counter.

Parameters

  • name – a counter name

  • elapsed – execution elapsed time in milliseconds to update the counter.

class pip_services3_components.count.ICounters

Bases: abc.ABC

Interface for performance counters that measure execution metrics. The performance counters measure how code is performing: how fast or slow, how many transactions performed, how many objects are stored, what was the latest transaction time and so on.

They are critical to monitor and improve performance, scalability and reliability of code in production.

begin_timing(name: str) → <module ‘pip_services3_components.count.CounterTiming’ from ‘/pip_services3_components/count/CounterTiming.py’>

Begins measurement of execution time interval. It returns CounterTiming object which has to be called at CounterTiming.end_timing() to end the measurement and update the counter.

Parameters

name – a counter name of Interval type.

Returns

a CounterTiming callback object to end timing.

increment(name: str, value: float)

Increments counter by given value.

Parameters

  • name – a counter name of Increment type.

  • value – a value to add to the counter.

increment_one(name: str)

Increments counter by 1.

Parameters

name – a counter name of Increment type.

last(name: str, value: float)

Records the last calculated measurement value. Usually this method is used by metrics calculated externally.

Parameters

  • name – a counter name of Last type.

  • value – a last value to record.

stats(name: str, value: float)

Calculates min/average/max statistics based on the current and previous values.

Parameters

  • name – a counter name of Statistics type

  • value – a value to update statistics

timestamp(name: str, value: datetime.datetime)

Records the given timestamp.

Parameters

  • name – a counter name of Timestamp type.

  • value – a timestamp to record.

timestamp_now(name: str)

Records the current time as a timestamp.

Parameters

name – a counter name of Timestamp type.

class pip_services3_components.count.LogCounters

Bases: pip_services3_components.count.CachedCounters.CachedCounters, pip_services3_commons.refer.IReferenceable.IReferenceable

Performance counters that periodically dumps counters measurements to logger.

### Configuration parameters ###
  • options:

    • interval: interval in milliseconds to save current counters measurements (default: 5 mins)

    • reset_timeout: timeout in milliseconds to reset the counters. 0 disables the reset (default: 0)

### References ###

  • *:logger:*:*:1.0 ILogger components to dump the captured counters

  • *:context-info:*:*:1.0 (optional) ContextInfo to detect the context id and specify counters source

Example:

counters = LogCounters()
counters.set_references(References.from_tuples(
            Descriptor("pip-services", "logger", "console", "default", "1.0"), ConsoleLogger()))

counters.increment("mycomponent.mymethod.calls")
timing = counters.begin_timing("mycomponent.mymethod.exec_time")
# do something
timing.end_timing()
set_references(references: pip_services3_commons.refer.IReferences.IReferences)

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

class pip_services3_components.count.NullCounters

Bases: pip_services3_components.count.ICounters.ICounters

Dummy implementation of performance counters that doesn’t do anything. It can be used in testing or in situations when counters is required but shall be disabled.

begin_timing(name: str) → pip_services3_components.count.CounterTiming.CounterTiming

Begins measurement of execution time interval. It returns CounterTiming object which has to be called at end_timing to end the measurement and update the counter.

Parameters

name – a counter name of Interval type.

Returns

a CounterTiming callback object to end timing.

increment(name: str, value: float)

Increments counter by given value.

Parameters

  • name – a counter name of Increment type.

  • value – a value to add to the counter.

increment_one(name: str)

Increments counter by 1.

Parameters

name – a counter name of Increment type.

last(name: str, value: float)

Records the last calculated measurement value. Usually this method is used by metrics calculated externally.

Parameters

  • name – a counter name of Last type.

  • value – a last value to record.

stats(name: str, value: float)

Calculates min/average/max statistics based on the current and previous values.

Parameters

  • name – a counter name of Statistics type

  • value – a value to update statistics

timestamp(name: str, value: datetime.datetime)

Records the given timestamp.

Parameters

  • name – a counter name of Timestamp type.

  • value – a timestamp to record.

timestamp_now(name: str)

Records the current time as a timestamp.

Parameters

name – a counter name of Timestamp type.