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 logging-basic-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, forkable=False)¶

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).

When setting the forkable flag the OneAgent SDK for Python will only be partly initialized. In this special parent-initialized initialization state, only the following functions can be called:

All functions that are valid to call before calling initialize remain valid.
oneagent.sdk.SDK.agent_version_string() works as expected.
oneagent.sdk.SDK.agent_state() will return
oneagent.common.AgentState.TEMPORARILY_INACTIVE - but see the note below.
oneagent.sdk.SDK.set_diagnostic_callback() and oneagent.sdk.SDK.set_verbose_callback() work as expected, the callback will be carried over to forked child processes.
It is recommended you call shutdown() when the original process will not fork any more
children that want to use the SDK.

After you fork, the child becomes pre-initialized: the first call to an SDK function that needs a fully initialized agent will automatically complete the initialization.

You can still fork another child (e.g. in a double-fork scenario) in the pre-initialized state. However if you fork another child in the fully initialized state, it will not be able to use the SDK - not even if it tries to shut down the SDK and initialize it again.

Note

Calling oneagent.sdk.SDK.agent_state() in the pre-initialized state will cause the agent to become fully initialized.

All children forked from a parent-initialized process will use the same agent. That agent will shut down when all child processes and the original parent-initialized process have terminated or called shutdown. Calling shutdown() in a pre-initialized process is not required otherwise.

Parameters:

sdkopts (Iterable[str]) – A sequence of strings of the form NAME=VALUE that set the given SDK options. Ignored 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.
forkable (bool) – Use the SDK in ‘forkable’ mode.

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.

Note

Please note that SQL database traces are only created if they occur within some other SDK trace (e.g. incoming remote call).

Parameters:

database (DbInfoHandle) – Database information (see create_database_info()).
sql (str) – The SQL statement to trace.

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

create_in_process_link()¶

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.

trace_in_process_link(link_bytes)¶

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 the agent warning callback function.

The agent warning callback is called whenever one of the following happens while executing an SDK function:

An SDK usage error is detected or
An unexpected or unusual event (e.g. out of memory) prevented an operation from completing successfully.

The application must not call any SDK functions from the callback.

There is no default warning callback. It is recommended you set one for development and debugging, as this is the main way the SDK reports errors.

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.

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.

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

Warning

This method was originally meant to return a unicode object on Python 2 and a str on Python 3 and was documented as such until version 1.4. However, it has always been returning bytes only. Use .decode('utf-8') (bytes.decode()) if you need an actual string.

property 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:

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

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.

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.

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: 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: Tracer

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

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

Bases: Tracer, OutgoingTaggable

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

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

Bases: 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: Tracer, 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: Tracer

Traces in-process asynchronous execution.

See oneagent.sdk.SDK.create_in_process_link() and oneagent.sdk.SDK.trace_in_process_link() for more information.

New in version 1.1.0.

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

Bases: Tracer, 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: 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: 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: 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 (as a string tag).

oneagent.common.DYNATRACE_MESSAGE_PROPERTY_NAME = 'dtdTraceTagInfo'¶: The Dynatrace Tag messaging property name which is is used to transport the tag between agents (as a byte tag).

New in version 1.3.

oneagent.common.DYNATRACE_MESSAGE_PROPERTYNAME = 'dtdTraceTagInfo'¶: DEPRECATED alias for DYNATRACE_MESSAGE_PROPERTY_NAME

Deprecated since version 1.3.

class oneagent.common.AgentState¶

Bases: _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: _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.

NO_DATA = 2952658958¶: The operation completed without error, but there was no data to return.

class oneagent.common.AgentForkState¶

Bases: _Uninstantiable

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

PARENT_INITIALIZED = 1¶: SDK cannot be used in this process, but forked processes may use the SDK. This is the state of the process that called oneagent.initialize() with forkable=True

PRE_INITIALIZED = 2¶: Forked processes can use the SDK. Using the SDK in this process is allowed but changes the state to FULLY_INITIALIZED This is the state of all child processes of a process that is PARENT_INITIALIZED.

FULLY_INITIALIZED = 3¶: SDK can be used, forked processes may not use the SDK. This is the state of a process that was previously PRE_INITIALIZED and then called an SDK function.

NOT_FORKABLE = 4¶: SDK can be used, forked processes may not use the SDK, oneagent.initialize() was called without forkable=True.

ERROR = -1¶: Some error occurred while trying to determine the agent fork state.

class oneagent.common.MessageSeverity¶

Bases: _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: _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: _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: _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: _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: 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: SDKHandleBase

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

class oneagent.common.WebapplicationInfoHandle(nsdk, handle)¶

Bases: SDKHandleBase

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

class oneagent.common.MessagingSystemInfoHandle(nsdk, handle)¶

Bases: SDKHandleBase

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

class oneagent.common.TraceContextInfo(is_valid, trace_id, span_id)¶

Bases: object

Provides information about a PurePath node using the TraceContext (Trace-Id, Span-Id) model as defined in https://www.w3.org/TR/trace-context.

The Span-Id represents the currently active PurePath node (tracer). This Trace-Id and Span-Id information is not intended for tagging and context-propagation scenarios and primarily designed for log-enrichment use cases.

Note that contrary to other info objects, no manual cleanup (delete calls or similar) are required (or possible) for this class.

INVALID_TRACE_ID = '00000000000000000000000000000000'¶: All-zero (invalid) W3C trace ID.

INVALID_SPAN_ID = '0000000000000000'¶: All-zero (invalid) W3C span ID.

is_valid: bool¶: If true, the trace & span ID are both valid (i.e., non-zero). As an alternative to this property, you can check the truth value of the TraceContextInfo instance.

trace_id: str¶: The W3C trace ID hex string (never empty or None, but might be all-zero)

span_id: str¶: The W3C span ID hex string (never empty or None, but might be all-zero)

oneagent-sdk API Reference¶

Module `oneagent` (initialization)¶

Module `oneagent.sdk`¶

Module `oneagent.sdk.tracers`¶

Module `oneagent.common`¶

Table of Contents

Previous topic

Next topic

oneagent-sdk API Reference¶

Module oneagent (initialization)¶

Module oneagent.sdk¶

Module oneagent.sdk.tracers¶

Module oneagent.common¶

Module `oneagent` (initialization)¶

Module `oneagent.sdk`¶

Module `oneagent.sdk.tracers`¶

Module `oneagent.common`¶