# osprofiler package

## Subpackages

- osprofiler.cmd package
  - Submodules
  - osprofiler.cmd.cliutils module
    - `add_arg()`
    - `arg()`
    - `env()`
  - osprofiler.cmd.commands module
    - `BaseCommand`
      - `BaseCommand.group_name`
    - `TraceCommands`
      - `TraceCommands.group_name`
      - `TraceCommands.list()`
      - `TraceCommands.show()`
  - osprofiler.cmd.shell module
    - `OSProfilerShell`
    - `main()`
  - Module contents
- osprofiler.drivers package
  - Submodules
  - osprofiler.drivers.base module
    - `Driver`
      - `Driver.default_trace_fields`
      - `Driver.get_name()`
      - `Driver.get_report()`
      - `Driver.list_error_traces()`
      - `Driver.list_traces()`
      - `Driver.notify()`
    - `get_driver()`
  - osprofiler.drivers.elasticsearch_driver module
    - `ElasticsearchDriver`
      - `ElasticsearchDriver.get_name()`
      - `ElasticsearchDriver.get_report()`
      - `ElasticsearchDriver.list_error_traces()`
      - `ElasticsearchDriver.list_traces()`
      - `ElasticsearchDriver.notify()`
      - `ElasticsearchDriver.notify_error_trace()`
  - osprofiler.drivers.jaeger module
    - `Jaeger`
      - `Jaeger.create_span_tags()`
      - `Jaeger.get_name()`
      - `Jaeger.get_report()`
      - `Jaeger.list_error_traces()`
      - `Jaeger.list_traces()`
      - `Jaeger.notify()`
  - osprofiler.drivers.loginsight module
    - `LogInsightClient`
      - `LogInsightClient.CURRENT_SESSIONS_PATH`
      - `LogInsightClient.EVENTS_INGEST_PATH`
      - `LogInsightClient.LI_OSPROFILER_AGENT_ID`
      - `LogInsightClient.QUERY_EVENTS_BASE_PATH`
      - `LogInsightClient.SESSIONS_PATH`
      - `LogInsightClient.login()`
      - `LogInsightClient.query_events()`
      - `LogInsightClient.send_event()`
    - `LogInsightDriver`
      - `LogInsightDriver.get_name()`
      - `LogInsightDriver.get_report()`
      - `LogInsightDriver.notify()`
  - osprofiler.drivers.messaging module
    - `Messaging`
      - `Messaging.get_name()`
      - `Messaging.get_report()`
      - `Messaging.notify()`
    - `NotifyEndpoint`
      - `NotifyEndpoint.get_last_read_time()`
      - `NotifyEndpoint.get_messages()`
      - `NotifyEndpoint.info()`
    - `SignalExit`
    - `signal_handler()`
  - osprofiler.drivers.mongodb module
    - `MongoDB`
      - `MongoDB.get_name()`
      - `MongoDB.get_report()`
      - `MongoDB.list_error_traces()`
      - `MongoDB.list_traces()`
      - `MongoDB.notify()`
      - `MongoDB.notify_error_trace()`
  - osprofiler.drivers.otlp module
    - `OTLP`
      - `OTLP.create_span_tags()`
      - `OTLP.get_name()`
      - `OTLP.get_report()`
      - `OTLP.list_error_traces()`
      - `OTLP.list_traces()`
      - `OTLP.notify()`
  - osprofiler.drivers.redis_driver module
    - `Redis`
      - `Redis.get_name()`
      - `Redis.get_report()`
      - `Redis.list_error_traces()`
      - `Redis.list_traces()`
      - `Redis.notify()`
      - `Redis.notify_error_trace()`
    - `RedisSentinel`
      - `RedisSentinel.get_name()`
  - osprofiler.drivers.sqlalchemy_driver module
    - `SQLAlchemyDriver`
      - `SQLAlchemyDriver.get_name()`
      - `SQLAlchemyDriver.get_report()`
      - `SQLAlchemyDriver.list_traces()`
      - `SQLAlchemyDriver.notify()`
  - Module contents

## Submodules

## osprofiler.exc module

exception osprofiler.exc.CommandError(message=None)

  Bases: `Exception`

  Invalid usage of CLI.

exception osprofiler.exc.LogInsightAPIError

  Bases: `Exception`

exception osprofiler.exc.LogInsightLoginTimeout

  Bases: `Exception`

## osprofiler.initializer module

osprofiler.initializer.init_from_conf(conf, context, project, service, host, **kwargs)

  Initialize notifier from service configuration

  Parameters:

    - conf – service configuration

    - context – request context

    - project – project name (keystone, cinder etc.)

    - service – service name that will be profiled

    - host – hostname or host IP address that the service will be running on.

    - kwargs – other arguments for notifier creation

## osprofiler.notifier module

osprofiler.notifier.clear_notifier_cache()

osprofiler.notifier.create(connection_string, *args, **kwargs)

  Create notifier based on specified plugin_name

  Parameters:

    - connection_string – connection string which specifies the storage driver for notifier

    - args – args that will be passed to the driver’s __init__ method

    - kwargs – kwargs that will be passed to the driver’s __init__ method

  Returns:

    Callable notifier method

osprofiler.notifier.get()

  Returns notifier callable.

osprofiler.notifier.notify(info)

  Passes the profiling info to the notifier callable.

  Parameters:

    info – dictionary with profiling information

osprofiler.notifier.set(notifier)

  Service that are going to use profiler should set callable notifier.

  Callable notifier is instance of callable object, that accept exactly one argument “info”. “info” - is dictionary of values that contains profiling information.

## osprofiler.opts module

osprofiler.opts.list_opts()

osprofiler.opts.set_defaults(conf, enabled=None, trace_sqlalchemy=None, hmac_keys=None, connection_string=None, es_doc_type=None, es_scroll_time=None, es_scroll_size=None, socket_timeout=None, sentinel_service_name=None)

## osprofiler.profiler module

class osprofiler.profiler.Trace(name, info=None)

  Bases: `object`

class osprofiler.profiler.TracedMeta(cls_name, bases, attrs)

  Bases: `type`

  Metaclass to comfortably trace all children of a specific class.

  Possible usage:

      >>>  class RpcManagerClass(object, metaclass=profiler.TracedMeta):
      >>>      __trace_args__ = {'name': 'rpc',
      >>>                        'info': None,
      >>>                        'hide_args': False,
      >>>                        'hide_result': True,
      >>>                        'trace_private': False}
      >>>
      >>>      def my_method(self, some_args):
      >>>          pass
      >>>
      >>>      def my_method2(self, some_arg1, some_arg2, kw=None, kw2=None)
      >>>          pass

  Adding of this metaclass requires to set __trace_args__ attribute to the class we want to modify. __trace_args__ is the dictionary with one mandatory key included - “name”, that will define name of action to be traced - E.g. wsgi, rpc, db, etc…

osprofiler.profiler.clean()

osprofiler.profiler.get()

  Get profiler instance.

  Returns:

    Profiler instance or None if profiler wasn’t inited.

osprofiler.profiler.init(hmac_key, base_id=None, parent_id=None)

  Init profiler instance for current thread.

  You should call profiler.init() before using osprofiler. Otherwise profiler.start() and profiler.stop() methods won’t do anything.

  Parameters:

    - hmac_key – secret key to sign trace information.

    - base_id – Used to bind all related traces.

    - parent_id – Used to build tree of traces.

  Returns:

    Profiler instance

osprofiler.profiler.start(name, info=None)

  Send new start notification if profiler instance is presented.

  Parameters:

    - name – The name of action. E.g. wsgi, rpc, db, etc..

    - info – Dictionary with extra trace information. For example in wsgi it can be url, in rpc - message or in db sql - request.

osprofiler.profiler.stop(info=None)

  Send new stop notification if profiler instance is presented.

osprofiler.profiler.trace(name, info=None, hide_args=False, hide_result=True, allow_multiple_trace=True)

  Trace decorator for functions.

  Very useful if you would like to add trace point on existing function:

  >> @profiler.trace(“my_point”) >> def my_func(self, some_args): >> #code

  Parameters:

    - name – The name of action. E.g. wsgi, rpc, db, etc..

    - info – Dictionary with extra trace information. For example in wsgi it can be url, in rpc - message or in db sql - request.

    - hide_args – Don’t push to trace info args and kwargs. Quite useful if you have some info in args that you wont to share, e.g. passwords.

    - hide_result – Boolean value to hide/show function result in trace. True - hide function result (default). False - show function result in trace.

    - allow_multiple_trace – If the wrapped function has already been traced either allow the new trace to occur or raise a value error denoting that multiple tracing is not allowed (by default allow).

osprofiler.profiler.trace_cls(name, info=None, hide_args=False, hide_result=True, trace_private=False, allow_multiple_trace=True, trace_class_methods=False, trace_static_methods=False)

  Trace decorator for instances of class .

  Very useful if you would like to add trace point on existing method:

  >> @profiler.trace_cls(“rpc”) >> RpcManagerClass(object): >> >> def my_method(self, some_args): >> pass >> >> def my_method2(self, some_arg1, some_arg2, kw=None, kw2=None) >> pass >>

  Parameters:

    - name – The name of action. E.g. wsgi, rpc, db, etc..

    - info – Dictionary with extra trace information. For example in wsgi it can be url, in rpc - message or in db sql - request.

    - hide_args – Don’t push to trace info args and kwargs. Quite useful if you have some info in args that you wont to share, e.g. passwords.

    - hide_result – Boolean value to hide/show function result in trace. True - hide function result (default). False - show function result in trace.

    - trace_private – Trace methods that starts with “_”. It wont trace methods that starts “__” even if it is turned on.

    - trace_static_methods – Trace staticmethods. This may be prone to issues so careful usage is recommended (this is also why this defaults to false).

    - trace_class_methods – Trace classmethods. This may be prone to issues so careful usage is recommended (this is also why this defaults to false).

    - allow_multiple_trace – If wrapped attributes have already been traced either allow the new trace to occur or raise a value error denoting that multiple tracing is not allowed (by default allow).

## osprofiler.requests module

osprofiler.requests.enable()

osprofiler.requests.send(self, request, *args, **kwargs)

## osprofiler.sqlalchemy module

osprofiler.sqlalchemy.add_tracing(sqlalchemy, engine, name, hide_result=True)

  Add tracing to all sqlalchemy calls.

osprofiler.sqlalchemy.disable()

  Disable tracing of all DB queries. Reduce a lot size of profiles.

osprofiler.sqlalchemy.enable()

  add_tracing adds event listeners for sqlalchemy.

osprofiler.sqlalchemy.handle_error(exception_context)

  Handle SQLAlchemy errors

osprofiler.sqlalchemy.wrap_session(sqlalchemy, sess)

## osprofiler.web module

class osprofiler.web.WsgiMiddleware(application, hmac_keys=None, enabled=False, **kwargs)

  Bases: `object`

  WSGI Middleware that enables tracing for an application.

  classmethod factory(global_conf, **local_conf)

osprofiler.web.X_TRACE_HMAC = 'X-Trace-HMAC'

  Http header that will contain the traces data hmac (that will be validated).

osprofiler.web.X_TRACE_INFO = 'X-Trace-Info'

  Http header that will contain the needed traces data.

osprofiler.web.disable()

  Disable middleware.

  This is the alternative way to disable middleware. It will be used to be able to disable middleware via oslo.config.

osprofiler.web.enable(hmac_keys=None)

  Enable middleware.

osprofiler.web.get_trace_id_headers()

  Adds the trace id headers (and any hmac) into provided dictionary.

## Module contents

this page last updated: 2026-03-27 00:00:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug