oneagent-sdk API Reference

For a high-level overview of SDK concepts, see https://github.com/Dynatrace/OneAgent-SDK.

Module oneagent (initialization)

oneagent main module. Contains initialization and logging functionality.

oneagent.logger

The logging.Logger on which managed Python SDK messages will be written.

This logger has set the log level so that no messages are displayed by default. Use, for example, oneagent.logger.setLevel(logging.INFO) to see them. See Basic Logging Tutorial in the official Python documentation for more on configuring the logger.

class oneagent.InitResult

Information about the success of a call to initialize(). Instances of this class are falsy iff status is negative.

status

A int with more information about the status. One of the .STATUS_* constants in this class.

error

A Exception that occured during this initialization attempt. Usually, but not necessarily a oneagent.common.SDKError. Another exception class might indicate an incompatible Python version.

STATUS_STUB_LOAD_ERROR

A negative status code, meaning that the native SDK stub could not be loaded. This usually indicates that the Dynatrace OneAgent SDK for Python was incorrectly installed (but see error). Note that even in this case, a dummy implementation of the SDK is available so that calls to SDK functions do not fail (but they will be no-ops).

STATUS_INIT_ERROR

A negative status code, meaning that error occurred during initialization of the SDK. This usually indicates a problem with the Dynatrace OneAgent installation on the host (but see error).

STATUS_INITIALIZED

This status code is equal to zero and means that the SDK has successfully been initialized. error is always None with this status.

STATUS_INITIALIZED_WITH_WARNING

A positive status code meaning that the SDK has sucessfully been initialized, but there have been some warnings (e.g., some options could not be processed, or the agent is permanently inactive).

STATUS_ALREADY_INITIALIZED

A positive status code meaning that the SDK has already been initialized (not necessarily with success), i.e., initialize() has already been called. error is always None with this status.

oneagent.sdkopts_from_commandline(argv=None, remove=False, prefix='--dt_')

Creates a SDK option list for use with the sdkopts parameter of initialize() from a list argv of command line parameters.

An element in argv is treated as an SDK option if starts with prefix. The return value of this function will then contain the remainder of that parameter (without the prefix). If remove is True, these arguments will be removed from argv.

Parameters

  • argv (Iterable[str] or MutableSequence[str]) – An iterable of command line parameter strings. Defaults to sys.argv. Must be a MutableSequence if remove is True.

  • remove (bool) – Whether to remove a command line parameter that was recognized as an SDK option from argv (if True) or leave argv unmodified (if False). If True, argv must be a MutableSequence.

  • prefix (str) – The prefix string by which SDK options are recognized and which is removed from the copy of the command line parameter that is added to the return value.

Return type

list[str]

oneagent.get_sdk()

Returns a shared oneagent.sdk.SDK instance.

Repeated calls to this function are supported and will always return the same object.

Note

You have to initialize the SDK first using initialize() before this function will return a valid SDK instance.

New in version 1.1.0.

oneagent.initialize(sdkopts=(), sdklibname=None)

Attempts to initialize the SDK with the specified options.

Even if initialization fails, a dummy SDK will be available so that SDK functions can be called but will do nothing.

If you call this function multiple times, you must call shutdown() just as many times. The options from all but the first initialize call will be ignored (the return value will have the InitResult.STATUS_ALREADY_INITIALIZED status code in that case).

Parameters

  • sdkopts (Iterable[str]) – A sequence of strings of the form NAME=VALUE that set the given SDK options. Igored in all but the first initialize call.

  • sdklibname (str) – The file or directory name of the native C SDK DLL. If None, the shared library packaged directly with the agent is used. Using a value other than None is only acceptable for debugging. You are responsible for providing a native SDK version that matches the Python SDK version.

Return type

InitResult

oneagent.shutdown()

Shut down the SDK.

Returns

An exception object if an error occurred, a falsy value otherwise.

Return type

Exception

Module oneagent.sdk

SDK tracer factory functions and misc functions.

class oneagent.sdk.Channel

A (transport-layer) communication channel.

static __new__(_cls, type_, endpoint=None)

Creates a new Channel.

Parameters

  • type (int) – The type of the channel. See type_.

  • endpoint (str) – The channel endpoint. See endpoint.

type_

A int describing the type of the channel. One of the oneagent.common.ChannelType constants.

endpoint

An optional str describing the endpoint of the channel. See the documentation for the channel type constants for what this should be for each channel type.

class oneagent.sdk.SDK(native_sdk)

Bases: object

The main entry point to the Dynatrace SDK.

create_database_info(name, vendor, channel)

Creates a database info with the given information for use with trace_sql_database_request().

Parameters

  • name (str) – The name (e.g., connection string) of the database.

  • vendor (str) – The type of the database (e.g., sqlite, PostgreSQL, MySQL).

  • channel (Channel) – The channel used to communicate with the database.

Returns

A new handle, holding the given database information.

Return type

DbInfoHandle

create_web_application_info(virtual_host, application_id, context_root)

Creates a web application info for use with trace_incoming_web_request().

See <https://www.dynatrace.com/support/help/server-side-services/introduction/how-does-dynatrace-detect-and-name-services/#web-request-services> for more information about the meaning of the parameters.

Parameters

  • virtual_host (str) – The logical name of the web server that hosts the application.

  • application_id (str) – A unique ID for the web application. This will also be used as the display name.

  • context_root (str) –

    The context root of the web application. This is the common path prefix for requests which will be routed to the web application.

    If all requests to this server are routed to this application, use a slash '/'.

Return type

WebapplicationInfoHandle

trace_sql_database_request(database, sql)

Create a tracer for the given database info and SQL statement.

Parameters
Return type

tracers.DatabaseRequestTracer

trace_incoming_web_request(webapp_info, url, method, headers=None, remote_address=None, str_tag=None, byte_tag=None)

Create a tracer for an incoming webrequest.

Parameters

  • webapp_info (WebapplicationInfoHandle) – Web application information (see create_web_application_info()).

  • url (str) – The requested URL (including scheme, hostname/port, path and query).

  • method (str) – The HTTP method of the request (e.g., GET or POST).

  • headers (dict[str, str] or tuple[Collection[str], Collection[str]] or tuple[Iterable[str], Iterable[str], int]]) –

    The HTTP headers of the request. Can be either a dictionary mapping header name to value (str to str) or a tuple containing a sequence of string header names as first element, an equally long sequence of corresponding values as second element and optionally a count as third element (this will default to the len() of the header names).

    Some headers can appear multiple times in an HTTP request. To capture all the values, either use the tuple-form and provide the name and corresponding values for each, or if possible for that particular header, set the value to an appropriately concatenated string.

    Warning

    If you use Python 2, be sure to use the UTF-8 encoding or the unicode type! See here for more information.

  • remote_address (str) –

    The remote (client) IP address (of the peer of the socket connection via which the request was received).

    The remote address is useful to gain information about load balancers, proxies and ultimately the end user that is sending the request.

For the other parameters, see Tagging.

Return type

tracers.IncomingWebRequestTracer

trace_outgoing_web_request(url, method, headers=None)

Create a tracer for an outgoing webrequest.

Parameters

  • url (str) – The request URL (including scheme, hostname/port, path and query).

  • method (str) – The HTTP method of the request (e.g., GET or POST).

  • headers (dict[str, str] or tuple[Collection[str], Collection[str]] or tuple[Iterable[str], Iterable[str], int]]) –

    The HTTP headers of the request. Can be either a dictionary mapping header name to value (str to str) or a tuple containing a sequence of string header names as first element, an equally long sequence of corresponding values as second element and optionally a count as third element (this will default to the len() of the header names).

    Some headers can appear multiple times in an HTTP request. To capture all the values, either use the tuple-form and provide the name and corresponding values for each, or if possible for that particular header, set the value to an appropriately concatenated string.

    Warning

    If you use Python 2, be sure to use the UTF-8 encoding or the unicode type! See here for more information.

Return type

tracers.OutgoingWebRequestTracer

New in version 1.1.0.

trace_outgoing_remote_call(method, service, endpoint, channel, protocol_name=None)

Creates a tracer for outgoing remote calls.

Parameters

  • method (str) – The name of the service method/operation.

  • service (str) – The name of the service class/type.

  • endpoint (str) – A string identifying the “instance” of the the service. See also the general documentation on service endpoints.

  • channel (Channel) – The channel used to communicate with the service.

  • protocol_name (str) –

    The name of the remoting protocol (on top of the communication protocol specified in channel.type_.) that is used to to communicate with the service (e.g., RMI, Protobuf, …).

Return type

tracers.OutgoingRemoteCallTracer

trace_incoming_remote_call(method, name, endpoint, protocol_name=None, str_tag=None, byte_tag=None)

Creates a tracer for incoming remote calls.

For the parameters, see Tagging (str_tag and byte_tag) and trace_outgoing_remote_call() (all others).

Return type

tracers.IncomingRemoteCallTracer

Creates an in-process link.

An application can call this function to retrieve an in-process link, which can then be used to trace related processing at a later time and/or in a different thread.

In-process links allow an application to associate (link) tasks, that will be executed asynchronously in the same process, with the currently running task/operation. The linked tasks may be started and completed at arbitrary times - it’s not necessary for them to complete (or even start) before the “parent” operation to which they are linked completes.

For further information, see the high level SDK documentation at <https://github.com/Dynatrace/OneAgent-SDK/#in-process-linking>.

Note

  • If no tracer is active on the current thread, the retrieved link will be empty (have zero length).

  • Links returned by this function are not compatible with dynatrace string or byte tags, they can only be used with trace_in_process_link().

  • Links returned by this function can only be used in the process in which they were created.

Return type

bytes

New in version 1.1.0.

Creates a tracer for tracing asynchronous related processing in the same process.

For more information see create_in_process_link().

Parameters

link_bytes (bytes) – An in-process link created using create_in_process_link().

Return type

tracers.InProcessLinkTracer

New in version 1.1.0.

set_diagnostic_callback(callback)

Sets a callback to be informed of unusual events.

Unusual events include:

  • API usage errors.

  • Other unexpected events (like out of memory situations) that prevented an operation from completing successfully.

Warning

Use this as a development and debugging aid only. Your application should not rely on a calling sequence or any message content being set or passed to the callback.

Parameters

callback (callable) – The callback function. Receives the (unicode) error message as its only argument.

agent_state

Returns the current agent state (one of the constants in oneagent.common.AgentState).

Return type

int

agent_version_string

Returns the version string of the loaded SDK agent module.

If the agent has not been initialized yet this function will return an empty string.

Warning

Your application should not try to parse the version string or make any assumptions about it’s format.

Return type

str

agent_found

Returns whether an OneAgent could be found or not.

Return type

bool

New in version 1.1.0.

agent_is_compatible

Returns whether the found OneAgent is compatible with this version of the OneAgent SDK for Python.

Return type

bool

New in version 1.1.0.

add_custom_request_attribute(key, value)

Adds a custom request attribute to the current active tracer.

Parameters

  • key (str) – The name of the custom request attribute, the name is mandatory and may not be None.

  • value (str or int or float) – The value of the custom request attribute. Currently supported types are integer, float and string values. The value is mandatory and may not be None.

New in version 1.1.0.

create_messaging_system_info(vendor_name, destination_name, destination_type, channel)

Creates a messaging system info object.

This function creates a messaging system info object which is required for tracing sending, receiving and processing messages.

Parameters
Return type

MessagingSystemInfoHandle

New in version 1.2.0.

trace_outgoing_message(messaging_system_info)

Creates a tracer for tracing an outgoing message.

Parameters

messaging_system_info (MessagingSystemInfoHandle) – Messaging system information (see create_messaging_system_info())

Return type

tracers.OutgoingMessageTracer

New in version 1.2.0.

trace_incoming_message_receive(messaging_system_info)

Creates a tracer for tracing the receipt of an incoming message.

Tracing the receipt of the message is optional but may make sense if receiving may take a significant amount of time, e.g. when doing a blocking receive. It might make less sense when tracing a polling receive. If you do use a receive tracer, start and end the corresponding incoming message process tracer (see trace_incoming_message_process()) while the receive tracer is still active.

Parameters

messaging_system_info (MessagingSystemInfoHandle) – Messaging system information (see create_messaging_system_info())

Return type

tracers.IncomingMessageReceiveTracer

New in version 1.2.0.

trace_incoming_message_process(messaging_system_info, str_tag=None, byte_tag=None)

Creates a tracer for tracing the processing of an incoming message.

Use this tracer to trace the actual, logical processing of the message as opposed to the time it takes to receive it. If you use an incoming message receive tracer (see trace_incoming_message_receive()) to trace the receipt of the processed message, start and end the corresponding incoming message process tracer while the receive tracer is still active.

Parameters
Return type

tracers.IncomingMessageProcessTracer

New in version 1.2.0.

trace_custom_service(service_method, service_name)

Creates a tracer for custom services.

Custom service tracers are used to trace service calls for which there is no other suitable tracer. To create a custom service tracer, an application can simply call trace_custom_service().

For further information, see the high level SDK documentation at <https://github.com/Dynatrace/OneAgent-SDK/#customservice>

: param str service_method:

The name of the service method.

: param str service_name:

The name of the service.

Return type

tracers.CustomServiceTracer

New in version 1.2.0.

Module oneagent.sdk.tracers

Defines the public SDK tracer types (constructors should be considered private though).

Use the factory functions from oneagent.sdk.SDK to create tracers.

class oneagent.sdk.tracers.OutgoingTaggable

Bases: object

Mixin base class for tracers that support having other paths linked to them.

See also

Documentation on Tagging.

outgoing_dynatrace_string_tag

Get a string tag (str on Python 3, unicode on Python 2) identifying the node of this tracer. Must be called between starting and ending the tracer (i.e., while it is started).

outgoing_dynatrace_byte_tag

Get a bytes tag identifying the node of this tracer. Must be called between starting and ending the tracer (i.e., while it is started).

class oneagent.sdk.tracers.Tracer(nsdk, handle)

Bases: object

Base class for tracing of operations.

Note that tracer are not only not thread-safe but thread-affine: They may only ever be used on the thread that created them.

If a tracer object evaluates to False (i.e., is falsy), tracing has been rejected for some reason (e.g., because the agent is currently or permanently inactive). You may then skip adding more information to the tracer, which might speed up your application.

The usual life-cycle of a tracer is as follows:

  1. Create a tracer using the appropriate oneagent.sdk.SDK.trace_* method. The tracer is now in the unstarted state.

  2. Start the tracer (via start() or by using the tracer as a context manager, i.e., in a with-block). Timing starts here. The tracer is now started.

  3. Optionally mark the tracer as failed once (using mark_failed_exc(), mark_failed() or automatically when an exception leaves the with-block for which this tracer was used as a context manager). It is still started but also marked as failed.

  4. End the tracer (via end() or automatically by using the tracer as a context manager). Timing stops here. The tracer is now ended and no further operations are allowed on it.

Unless specified otherwise, all operations on tracer are only allowed in the started state.

You may short-circuit the life-cycle by calling end() already in the unstarted state (i.e., before starting the tracer). No nodes or path will be produced then. However, it is usually better to avoid creating the tracer in the first place instead of throwing it away unused that way.

Tracers can be used as context-managers, i.e., in with blocks:

with tracer:
    # code

This will start the tracer upon entering the with-block and end it upon leaving it. Additionally, if an exception leaves the block, mark_failed_exc() will be called on the tracer.

start()

Start the tracer and timing.

May only be called in the unstarted state. Transitions the state from unstarted to started.

Prefer using the tracer as a context manager (i.e., with a with-block) instead of manually calling this method.

end()

Ends the tracer.

May be called in any state. Transitions the state to ended and releases any SDK resources owned by this tracer (this includes only internal resources, things like passed-in oneagent.common.DbInfoHandle need to be released manually).

Prefer using the tracer as a context manager (i.e., with a with-block) instead of manually calling this method.

mark_failed(clsname, msg)

Marks the tracer as failed with the given exception class name clsname and message msg.

May only be called in the started state and only if the tracer is not already marked as failed. Note that this does not end the tracer! Once a tracer is marked as failed, attempts to do it again are forbidden.

If possible, using the tracer as a context manager (i.e., with a with-block) or mark_failed_exc() is more convenient than this method.

Parameters

  • clsname (str) – Fully qualified name of the exception type that caused the failure.

  • msg (str) – Exception message that caused the failure.

mark_failed_exc(e_val=None, e_ty=None)

Marks the tracer as failed with the given exception e_val of type e_ty (defaults to the current exception).

May only be called in the started state and only if the tracer is not already marked as failed. Note that this does not end the tracer! Once a tracer is marked as failed, attempts to do it again are forbidden.

If possible, using the tracer as a context manager (i.e., with a with-block) is more convenient than this method.

If e_val and e_ty are both none, the current exception (as retured by sys.exc_info()) is used.

Parameters

  • e_val (BaseException) – The exception object that caused the failure. If None, the current exception value (sys.exc_info()[1]) is used.

  • e_ty (type) – The type of the exception that caused the failure. If None the type of e_val is used. If that is also None, the current exception type (sys.exc_info()[0]) is used.

class oneagent.sdk.tracers.DatabaseRequestTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Traces a database request. See oneagent.sdk.SDK.trace_sql_database_request().

set_rows_returned(rows_returned)

Sets the number of retrieved rows for this traced database request.

Parameters

rows_returned (int) – The number of rows returned Must not be negative.

set_round_trip_count(round_trip_count)

Sets the number of round trips to the database server for this traced database request.

Parameters

round_trip_count (int) – The number of round trips. Must not be negative.

class oneagent.sdk.tracers.IncomingRemoteCallTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Traces an incoming remote call. See oneagent.sdk.SDK.trace_incoming_remote_call().

class oneagent.sdk.tracers.OutgoingRemoteCallTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer, oneagent.sdk.tracers.OutgoingTaggable

Traces an outgoing remote call. See oneagent.sdk.SDK.trace_outgoing_remote_call().

class oneagent.sdk.tracers.IncomingWebRequestTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Traces an incoming web (HTTP) request. See oneagent.sdk.SDK.trace_incoming_web_request().

Warning

Regarding HTTP header encoding issues see HTTP Request and Response Header Encoding.

add_parameter(name, value)
add_parameters(data)
add_parameters(names, values[, count])

Adds the request (POST/form) parameter(s) with the given name(s) and value(s).

add_parameter() adds a single parameter:

Parameters

  • name (str) – The name of the parameter.

  • value (str) – The value of the parameter.

add_parameters() adds multiple parameters and can be called either with a single mapping of parameter names to parameter values or with the names, corresponding values, and an optional count as separate iterables:

Parameters

  • data (dict[str, str]) – A dictionary mapping a parameter name to a (single) parameter value.

  • names (Iterable[str] or Collection[str]) – An iterable (if the count is given) or collection (if not) of strings with the parameter names.

  • values (Iterable[str] or Collection[str]) – An iterable (if the count is given) or collection (if not) of strings with the parameter values.

  • count (int) – An optional integer giving the count of values in names / values to use.

add_response_header(name, value)
add_response_headers(data)
add_response_headers(names, values[, count])

Adds the HTTP response header(s) with the given name(s) and value(s). For the parameters, see add_parameter() and add_parameters().

Some headers can appear multiple times in an HTTP response. To capture all the values, either call add_response_header() multiple times, or use the signature with names and values as separate values and provide the name and corresponding values for each, or, if possible for that particular header, set the value to an appropriately concatenated string.

set_status_code(code)

Sets the HTTP status code for the response to the traced incoming request.

Parameters

code (int) – The HTTP status code of the HTTP response that is sent back to the client (e.g., 200 or 404).

class oneagent.sdk.tracers.OutgoingWebRequestTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer, oneagent.sdk.tracers.OutgoingTaggable

Traces an outgoing web (HTTP) request. See oneagent.sdk.SDK.trace_outgoing_web_request().

Warning

Regarding HTTP header encoding issues see HTTP Request and Response Header Encoding.

add_response_header(name, value)
add_response_headers(data)
add_response_headers(names, values[, count])

Adds the HTTP response header(s) with the given name(s) and value(s). For the parameters, see add_parameter() and add_parameters().

Some headers can appear multiple times in an HTTP response. To capture all the values, either call add_response_header() multiple times, or use the signature with names and values as separate values and provide the name and corresponding values for each, or, if possible for that particular header, set the value to an appropriately concatenated string.

New in version 1.1.0.

set_status_code(code)

Sets the HTTP status code for the response of the traced outgoing request.

Parameters

code (int) – The HTTP status code of the HTTP response (e.g., 200 or 404).

New in version 1.1.0.

class oneagent.sdk.tracers.InProcessLinkTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Traces in-process asynchronous execution.

New in version 1.1.0.

class oneagent.sdk.tracers.OutgoingMessageTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer, oneagent.sdk.tracers.OutgoingTaggable

Tracer for outgoing messages.

See oneagent.sdk.SDK.trace_outgoing_message() for more information.

New in version 1.2.0.

set_vendor_message_id(message_id)

Sets the vendor message ID of an outgoing message.

Parameters

message_id (str) – The vendor message ID provided by the messaging system.

Note

This information is often only available after the message was sent. Thus, calling this function is also supported after starting the tracer.

New in version 1.2.0.

set_correlation_id(correlation_id)

Sets the corrrelation ID of an outgoing message.

Parameters

correlation_id (str) – The correlation ID for the message, usually application-defined.

Note

This information is often only available after the message was sent. Thus, calling this function is also supported after starting the tracer.

New in version 1.2.0.

class oneagent.sdk.tracers.IncomingMessageReceiveTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Tracer for receiving messages.

See oneagent.sdk.SDK.trace_incoming_message_receive() for more information.

New in version 1.2.0.

class oneagent.sdk.tracers.IncomingMessageProcessTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Tracer for processing incoming messages.

See oneagent.sdk.SDK.trace_incoming_message_process() for more information.

New in version 1.2.0.

set_vendor_message_id(message_id)

Sets the vendor message ID of an incoming message.

Parameters

message_id (str) – The message ID provided by the messaging system.

New in version 1.2.0.

set_correlation_id(correlation_id)

Sets the corrrelation ID of an incoming message.

Parameters

correlation_id (str) – The correlation ID for the message, usually application-defined.

New in version 1.2.0.

class oneagent.sdk.tracers.CustomServiceTracer(nsdk, handle)

Bases: oneagent.sdk.tracers.Tracer

Tracer for custom services.

See oneagent.sdk.SDK.trace_custom_service() for more information.

New in version 1.2.0.

Module oneagent.common

Defines basic SDK constants and classes.

All public names here are also re-exported from oneagent.sdk and should preferably be used from there.

oneagent.common.DYNATRACE_HTTP_HEADER_NAME = 'X-dynaTrace'

The Dynatrace Tag request header name which is used to transport the tag between agents.

class oneagent.common.AgentState

Bases: oneagent.common._Uninstantiable

Constants for the agent’s state. See oneagent.sdk.SDK.agent_state.

ACTIVE = 0

The SDK stub is connected to the agent, which is currently active.

TEMPORARILY_INACTIVE = 1

The SDK stub is connected to the agent, which is temporarily inactive.

PERMANENTLY_INACTIVE = 2

The SDK stub is connected to the agent, which is permanently inactive.

NOT_INITIALIZED = 3

The agent has not been initialized.

ERROR = -1

Some unexpected error occurred while trying to determine the agent state.

class oneagent.common.ErrorCode

Bases: oneagent.common._Uninstantiable

Constants for error codes of the native agent, as may be contained in SDKError.code.

SUCCESS = 0

The operation completed successfully. You usually won’t get any object with error code at all in that case.

GENERIC = 2952658945

The operation failed, but no more specific error code fits the failure.

INVALID_ARGUMENT = 2952658946

A function was called with an invalid argument.

NOT_IMPLEMENTED = 2952658947

The called function is not implemented.

NOT_INITIALIZED = 2952658948

The SDK has not been initialized.

OUT_OF_MEMORY = 2952658949

There is not enough available memory to complete the operation.

AGENT_NOT_ACTIVE = 2952658950

The native SDK stub was configured to _not_ try to load the actual agent module.

LOAD_AGENT = 2952658951

Either the OneAgent SDK for C/C++ or the OneAgent binary could not be loaded.

INVALID_AGENT_BINARY = 2952658952

The expected exports could not be found either in the OneAgent SDK for C/C++ or the OneAgent binary.

UNEXPECTED = 2952658953

The operation failed because of an unexpected error.

ENTRY_ALREADY_EXISTS = 2952658954

The command line argument / stub variable definition was ignored because an entry with the same key was already present.

FEATURE_LEVEL_NOT_SUPPORTED = 2952658955

The SDK agent module doesn’t support the feature level required by this version of the SDK stub.

INTERFACE_NOT_SUPPORTED = 2952658956

The SDK agent module doesn’t support the SDK interface required by this version of the SDK stub

FORK_CHILD = 2952658957

The operation failed because this is the child process of a fork that occurred while the SDK was initialized.

class oneagent.common.MessageSeverity

Bases: oneagent.common._Uninstantiable

Constants for the severity of log messages.

The levels with the lower numerical values include all messages of the ones with the higher values. Note that DEBUG is the highest severity, contrary to usual conventions.

FINEST = 0

Most verbose logging (higly detailed tracing).

FINER = 1

Slightly less verbose logging (fairly detailed tracing).

FINE = 2

Still verbose logging (informational tracing messages).

CONFIG = 3

Log configuration messages.

INFO = 4

Log informational messages.

WARNING = 5

Log conditions that indicate a potential problem.

SEVERE = 6

Log messages indicating a serious failure.

DEBUG = 7

Debug message. None should be logged by default, unless they are specifically enabled with special debug options. Note that contrary to usual conventions, this is the highest severity.

NONE = 8

No messages of this level exist, so using this level disables all log messages.

class oneagent.common.MessagingDestinationType

Bases: oneagent.common._Uninstantiable

Messaging Destination Type Constants

QUEUE = 1

A message queue: a message sent to this destination will be (successfully)

TOPIC = 2

A message topic: a message sent to this destination will be received by all

class oneagent.common.MessagingVendor

Bases: oneagent.common._Uninstantiable

Messaging System Vendor Strings

HORNETQ = 'HornetQ'

vendor string for HornetQ

ACTIVE_MQ = 'ActiveMQ'

vendor string for ActiveMQ

RABBIT_MQ = 'RabbitMQ'

vendor string for RabbitMQ

ARTEMIS = 'Artemis'

vendor string for Artemis

WEBSPHERE = 'WebSphere'

vendor string for WebSphere

MQSERIES_JMS = 'MQSeries JMS'

vendor string for MQSeries JMS

MQSERIES = 'MQSeries'

vendor string for MQSeries

TIBCO = 'Tibco'

vendor string for Tibco

class oneagent.common.DatabaseVendor

Bases: oneagent.common._Uninstantiable

String constants for well-known database vendors. Use for the vendor parameter of oneagent.sdk.SDK.create_database_info().

APACHE_HIVE = 'ApacheHive'

Database vendor string for Apache Hive.

CLOUDSCAPE = 'Cloudscape'

Database vendor string for Apache Derby (aka. IBM Cloudscape).

HSQLDB = 'HSQLDB'

Database vendor string for HyperSQL DB.

PROGRESS = 'Progress'

Database vendor string for OpenEdge Database (aka. Progress).

MAXDB = 'MaxDB'

Database vendor string for SAP MaxDB.

HANADB = 'HanaDB'

Database vendor string for SAP HANA DB.

INGRES = 'Ingres'

Database vendor string for Ingres Database.

FIRST_SQL = 'FirstSQL'

Database vendor string for FirstSQL.

ENTERPRISE_DB = 'EnterpriseDB'

Database vendor string for EnterpriseDB.

CACHE = 'Cache'

Database vendor string for InterSystems Cache.

ADABAS = 'Adabas'

Database vendor string for ADABAS.

FIREBIRD = 'Firebird'

Database vendor string for Firebird Database.

DB2 = 'DB2'

Database vendor string for IBM Db2.

DERBY_CLIENT = 'Derby Client'

Database vendor string for JDBC connections to Apache Derby (aka. IBM Cloudscape).

DERBY_EMBEDDED = 'Derby Embedded'

Database vendor string for Derby Embedded.

FILEMAKER = 'Filemaker'

Database vendor string for FileMaker Pro.

INFORMIX = 'Informix'

Database vendor string for IBM Informix.

INSTANT_DB = 'InstantDb'

Database vendor string for InstantDB.

INTERBASE = 'Interbase'

Database vendor string for Embarcadero InterBase.

MYSQL = 'MySQL'

Database vendor string for MySQL.

MARIADB = 'MariaDB'

Database vendor string for MariaDB.

NETEZZA = 'Netezza'

Database vendor string for IBM Netezza.

ORACLE = 'Oracle'

Database vendor string for Oracle Database.

PERVASIVE = 'Pervasive'

Database vendor string for Pervasive PSQL.

POINTBASE = 'Pointbase'

Database vendor string for PointBase.

POSTGRESQL = 'PostgreSQL'

Database vendor string for PostgreSQL.

SQLSERVER = 'SQL Server'

Database vendor string for Microsoft SQL Server.

SQLITE = 'sqlite'

Database vendor string for SQLite.

SYBASE = 'Sybase'

Database vendor string for SAP ASE (aka. Sybase SQL Server, Sybase DB, Sybase ASE).

TERADATA = 'Teradata'

Database vendor string for Teradata Database.

VERTICA = 'Vertica'

Database vendor string for Vertica.

CASSANDRA = 'Cassandra'

Database vendor string for Cassandra.

H2 = 'H2'

Database vendor string for H2 Database Engine.

COLDFUSION_IMQ = 'ColdFusion IMQ'

Database vendor string for ColdFusion In-Memory Query (aka. Query of Queries).

REDSHIFT = 'Amazon Redshift'

Database vendor string for Amazon Redshift.

class oneagent.common.ChannelType

Bases: oneagent.common._Uninstantiable

Constants for communication channel types, for use as oneagent.sdk.Channel.type_

OTHER = 0

Some other channel type or unknown channel type.

TCP_IP = 1

The channel is a TCP/IP connection.

The channel endpoint string should be the host name, followed by a colon, followed by the port number (in decimal). E.g. localhost:1234 or example.com:80.

UNIX_DOMAIN_SOCKET = 2

The channel is a connection via Unix domain sockets.

The channel endpoint string should be the path of the Unix domain sockets.

NAMED_PIPE = 3

The channel is a named pipe.

The channel endpoint string should be the pipe name.

IN_PROCESS = 4

The channel is some in-process means of communication.

exception oneagent.common.SDKError(code, msg)

Bases: Exception

Exception for SDK errors (mostly during initialization, see oneagent.initialize()).

code

An int error code. Can be one of the ErrorCode constants. If not, it is a Windows error code on Windows and an errno number on other systems.

message

The str error message associated with code (potentially contains more information than could be deduced from code alone).

exception oneagent.common.SDKInitializationError(code, msg, agent_version='-/-')

Bases: oneagent.common.SDKError

Exception for initialization errors.

agent_version

The str agent version associated with this error.

class oneagent.common.SDKHandleBase(nsdk, handle)

Bases: object

Base class for SDK handles that must be closed explicitly.

You can use this class as a context manager (i.e. with a with-block) to automatically close the handle.

close()

Closes the handle, if it is still open.

Usually, you should prefer using the handle as a context manager to calling close() manually.

class oneagent.common.DbInfoHandle(nsdk, handle)

Bases: oneagent.common.SDKHandleBase

Opaque handle to database information. See oneagent.sdk.SDK.create_database_info().

class oneagent.common.WebapplicationInfoHandle(nsdk, handle)

Bases: oneagent.common.SDKHandleBase

Opaque handle to web application information. See oneagent.sdk.SDK.create_web_application_info().

class oneagent.common.MessagingSystemInfoHandle(nsdk, handle)

Bases: oneagent.common.SDKHandleBase

Opaque handle for messaging system info object. See oneagent.sdk.SDK.create_messaging_system_info().