pip_services3_components.trace package

Submodules

• pip_services3_components.trace.CachedTracer module
• pip_services3_components.trace.CompositeTracer module
• pip_services3_components.trace.DefaultTracerFactory module
• pip_services3_components.trace.ITracer module
• pip_services3_components.trace.LogTracer module
• pip_services3_components.trace.NullTracer module
• pip_services3_components.trace.OperationTrace module
• pip_services3_components.trace.TraceTiming module

Module contents

class pip_services3_components.trace.CachedTracer

Bases: pip_services3_components.trace.ITracer.ITracer, pip_services3_commons.config.IReconfigurable.IReconfigurable, pip_services3_commons.refer.IReferenceable.IReferenceable, abc.ABC

Abstract tracer that caches recorded traces in memory and periodically dumps them. Child classes implement saving cached traces to their specified destinations.

### Configuration parameters ###

• source: source (context) name

• options:

  • interval: interval in milliseconds to save log messages (default: 10 seconds)

  • max_cache_size: maximum number of messages stored in this cache (default: 100)

### References ###

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

See ITracer, OperationTrace

begin_trace(correlation_id: Optional[str], component: str, operation: str) → pip_services3_components.trace.TraceTiming.TraceTiming

Begings recording an operation trace

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

Returns

a trace timing object.

clear()

Clears (removes) all cached log messages.

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

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

dump()

Dumps (writes) the currently cached log messages.

See _write

failure(correlation_id: Optional[str], component: str, operation: str, error: Exception, duration: float)

Records an operation failure with its name, duration and error

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• error – an error object associated with this trace.

• duration – execution duration in milliseconds.

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

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

trace(correlation_id: Optional[str], component: str, operation: str, duration: float)

Records an operation trace with its name and duration

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• duration – execution duration in milliseconds.

class pip_services3_components.trace.CompositeTracer(references: pip_services3_commons.refer.IReferences.IReferences = None)

Bases: pip_services3_components.trace.ITracer.ITracer, pip_services3_commons.refer.IReferenceable.IReferenceable

Aggregates all tracers from component references under a single component.

It allows to record traces and conveniently send them to multiple destinations.

### References ###

• *:tracer:*:*:1.0 (optional) ITracer components to pass operation traces

See ITracer

Example:

begin_trace(correlation_id: Optional[str], component: str, operation: str) → pip_services3_components.trace.TraceTiming.TraceTiming

Begings recording an operation trace

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

Returns

a trace timing object.

failure(correlation_id: Optional[str], component: str, operation: str, error: Exception, duration: float)

Records an operation failure with its name, duration and error

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• error – an error object associated with this trace.

• duration – execution duration in milliseconds.

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

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

trace(correlation_id: Optional[str], component: str, operation: str, duration: float) → None

Records an operation trace with its name and duration

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• duration – execution duration in milliseconds.

class pip_services3_components.trace.DefaultTracerFactory

Bases: pip_services3_components.build.Factory.Factory

Creates ITracer components by their descriptors.

See Factory, NullTracer, ConsoleTracer, CompositeTracer

CompositeTracerDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>

LogTracerDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>

NullTracerDescriptor = <pip_services3_commons.refer.Descriptor.Descriptor object>

class pip_services3_components.trace.ITracer

Bases: abc.ABC

Interface for tracer components that capture operation traces.

begin_trace(correlation_id: Optional[str], component: str, operation: str) → pip_services3_components.trace.TraceTiming.TraceTiming

Begings recording an operation trace

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

Returns

a trace timing object.

failure(correlation_id: Optional[str], component: str, operation: str, error: Exception, duration: float)

Records an operation failure with its name, duration and error

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• error – an error object associated with this trace.

• duration – execution duration in milliseconds.

trace(correlation_id: Optional[str], component: str, operation: str, duration: float)

Records an operation trace with its name and duration

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• duration – execution duration in milliseconds.

class pip_services3_components.trace.LogTracer

Bases: pip_services3_commons.config.IConfigurable.IConfigurable, pip_services3_commons.refer.IReferenceable.IReferenceable, pip_services3_components.trace.ITracer.ITracer

Tracer that dumps recorded traces to logger.

### Configuration parameters ###

• options:

  • log_level: log level to record traces (default: debug)

### 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

See ITracer, CachedCounters, CompositeLogger

Example:

begin_trace(correlation_id: Optional[str], component: str, operation: str) → pip_services3_components.trace.TraceTiming.TraceTiming

Begings recording an operation trace

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

Returns

a trace timing object.

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

Configures component by passing configuration parameters.

Parameters

config – configuration parameters to be set.

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

Sets references to dependent components.

Parameters

references – references to locate the component dependencies.

trace(correlation_id: Optional[str], component: str, operation: str, duration: float)

Records an operation trace with its name and duration

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• duration – execution duration in milliseconds.

class pip_services3_components.trace.NullTracer

Bases: pip_services3_components.trace.ITracer.ITracer

Dummy implementation of tracer that doesn’t do anything.

It can be used in testing or in situations when tracing is required but shall be disabled.

See ITracer

begin_trace(correlation_id: Optional[str], component: str, operation: str) → pip_services3_components.trace.TraceTiming.TraceTiming

Begings recording an operation traceBegings recording an operation trace

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

Returns

a trace timing object.

failure(correlation_id: Optional[str], component: str, operation: str, error: Exception, duration: float)

Records an operation failure with its name, duration and error

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• error – an error object associated with this trace.

• duration – execution duration in milliseconds.

trace(correlation_id: Optional[str], component: str, operation: str, duration: float)

Records an operation trace with its name and duration

Parameters

• correlation_id – (optional) transaction id to trace execution through call chain.

• component – a name of called component

• operation – a name of the executed operation.

• duration – execution duration in milliseconds.

Returns

class pip_services3_components.trace.OperationTrace(time: datetime.datetime, source: str, component: str, operation: str, correlation_id: str, duration: float, error: pip_services3_commons.errors.ErrorDescription.ErrorDescription)

Bases: object

Data object to store captured operation traces. This object is used by CachedTracer.

duration: float

The description of the captured error

ErrorDescription, ApplicationException

class pip_services3_components.trace.TraceTiming(correlation_id: Optional[str], component: str, operation: str, tracer: Optional[pip_services3_components.trace.ITracer.ITracer] = None)

Bases: object

CounterTiming object returned by beginTrace to end timing of execution block and record the associated trace.

Example:

end_failure(error: Exception)

Ends timing of a failed block, calculates elapsed time and records the associated trace.

Parameters

error – an error object associated with this trace.

end_trace()

Ends timing of an execution block, calculates elapsed time and records the associated trace.