Defines common types/constants/macros. Applications should not include this file directly. More...

Classes
struct	onesdk_stub_version_t
	Stores the stub version number. More...

Macros
#define	ONESDK_INVALID_HANDLE 0
	Invalid handle value (zero). More...

#define	ONESDK_DYNATRACE_HTTP_HEADER_NAME "X-dynaTrace"
	HTTP header name for the Dynatrace string tag. More...

Error Code Constants

#define	ONESDK_ERROR_GENERIC
	The operation failed, no further detail is available.

#define	ONESDK_ERROR_INVALID_ARGUMENT
	A function was called with an invalid argument.

#define	ONESDK_ERROR_NOT_IMPLEMENTED
	The called function is not implemented.

#define	ONESDK_ERROR_NOT_INITIALIZED
	The SDK has not been initialized.

#define	ONESDK_ERROR_OUT_OF_MEMORY
	Out of memory.

#define	ONESDK_ERROR_AGENT_NOT_ACTIVE
	The SDK stub was configured to not try to load the actual agent module.

#define	ONESDK_ERROR_LOAD_AGENT
	The loader module was unable to load the actual SDK agent module.

#define	ONESDK_ERROR_INVALID_AGENT_BINARY
	The loader module found an SDK agent binary that didn't have the expected exports.

#define	ONESDK_ERROR_UNEXPECTED
	The operation failed because of an unexpected error.

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

#define	ONESDK_ERROR_FEATURE_LEVEL_NOT_SUPPORTED
	The SDK agent module doesn't support the feature level required by this version of the SDK stub.

#define	ONESDK_ERROR_INTERFACE_NOT_SUPPORTED
	The SDK agent module doesn't support the SDK interface required by this version of the SDK stub.

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

#define	ONESDK_ERROR_NO_DATA
	The operation completed without error, but there was no data to return (this just has ERROR in the name for consistency).

#define	ONESDK_SUCCESS
	The operation completed successfully.

Logging Level Constants
Allows choosing a log level. Lower levels include higher ones. See also onesdk_stub_set_logging_level
#define	ONESDK_LOGGING_LEVEL_FINEST 0
	Most verbose logging level.

#define	ONESDK_LOGGING_LEVEL_FINER 1
	Log even finer messages.

#define	ONESDK_LOGGING_LEVEL_FINE 2
	Log fine messages.

#define	ONESDK_LOGGING_LEVEL_CONFIG 3
	Log config-related messages.

#define	ONESDK_LOGGING_LEVEL_INFO 4
	Log info messages.

#define	ONESDK_LOGGING_LEVEL_WARNING 5
	Log warning messages.

#define	ONESDK_LOGGING_LEVEL_SEVERE 6
	Least verbose regular logging level.

#define	ONESDK_LOGGING_LEVEL_DEBUG 7
	Only used for debug messages which are not enabled by default.

#define	ONESDK_LOGGING_LEVEL_NONE 8
	Default SDK stub logging level. Setting this log level deactivates all logging.

Agent State Constants
See also onesdk_agent_get_current_state
#define	ONESDK_AGENT_STATE_ACTIVE 0
	The SDK stub is connected to the agent, which is currently active. More...

#define	ONESDK_AGENT_STATE_TEMPORARILY_INACTIVE 1
	The SDK stub is connected to the agent, which is temporarily inactive. More...

#define	ONESDK_AGENT_STATE_PERMANENTLY_INACTIVE 2
	The SDK stub is connected to the agent, which is permanently inactive. More...

#define	ONESDK_AGENT_STATE_NOT_INITIALIZED 3
	The agent has not been initialized. More...

#define	ONESDK_AGENT_STATE_ERROR (-1)
	Some unexpected error occurred while trying to determine the agent state.

Agent Forking State Constants
The fork-related state the agent is in, only relevant if you used ONESDK_INIT_FLAG_FORKABLE. See also ONESDK_INIT_FLAG_FORKABLE onesdk_agent_get_fork_state
#define	ONESDK_AGENT_FORK_STATE_PARENT_INITIALIZED 1
	SDK cannot be used, forked processes may use SDK.

#define	ONESDK_AGENT_FORK_STATE_PRE_INITIALIZED 2
	Forked processes can use the SDK. Using the SDK in this process is allowed but changes the state to ONESDK_AGENT_FORK_STATE_FULLY_INITIALIZED.

#define	ONESDK_AGENT_FORK_STATE_FULLY_INITIALIZED 3
	SDK can be used, forked processes may not use the SDK.

#define	ONESDK_AGENT_FORK_STATE_NOT_FORKABLE 4
	SDK can be used, forked processes may not use the SDK, the agent was initialized without ONESDK_INIT_FLAG_FORKABLE.

#define	ONESDK_AGENT_FORK_STATE_ERROR (-1)
	Some error occurred while trying to determine the agent fork state.

Channel Type Constants
See also Channel Types and Endpoints
#define	ONESDK_CHANNEL_TYPE_OTHER 0
	Some other channel type or unknown channel type. More...

#define	ONESDK_CHANNEL_TYPE_TCP_IP 1
	The channel is a TCP/IP connection. More...

#define	ONESDK_CHANNEL_TYPE_UNIX_DOMAIN_SOCKET 2
	The channel is a connection via Unix domain sockets. More...

#define	ONESDK_CHANNEL_TYPE_NAMED_PIPE 3
	The channel is a named pipe. More...

#define	ONESDK_CHANNEL_TYPE_IN_PROCESS 4
	The channel is some in-process means of communication. More...

Database Vendor Strings
See also Database Request Tracers, https://github.com/Dynatrace/OneAgent-SDK/#database
#define	ONESDK_DATABASE_VENDOR_APACHE_HIVE "ApacheHive"
	Database vendor string for Apache Hive.

#define	ONESDK_DATABASE_VENDOR_CLOUDSCAPE "Cloudscape"
	Database vendor string for Apache Derby (aka. IBM Cloudscape).

#define	ONESDK_DATABASE_VENDOR_HSQLDB "HSQLDB"
	Database vendor string for HyperSQL DB.

#define	ONESDK_DATABASE_VENDOR_PROGRESS "Progress"
	Database vendor string for OpenEdge Database (aka. Progress).

#define	ONESDK_DATABASE_VENDOR_MAXDB "MaxDB"
	Database vendor string for SAP MaxDB.

#define	ONESDK_DATABASE_VENDOR_HANADB "HanaDB"
	Database vendor string for SAP HANA DB.

#define	ONESDK_DATABASE_VENDOR_INGRES "Ingres"
	Database vendor string for Ingres Database.

#define	ONESDK_DATABASE_VENDOR_FIRST_SQL "FirstSQL"
	Database vendor string for FirstSQL.

#define	ONESDK_DATABASE_VENDOR_ENTERPRISE_DB "EnterpriseDB"
	Database vendor string for EnterpriseDB.

#define	ONESDK_DATABASE_VENDOR_CACHE "Cache"
	Database vendor string for InterSystems Cache.

#define	ONESDK_DATABASE_VENDOR_ADABAS "Adabas"
	Database vendor string for ADABAS.

#define	ONESDK_DATABASE_VENDOR_FIREBIRD "Firebird"
	Database vendor string for Firebird Database.

#define	ONESDK_DATABASE_VENDOR_DB2 "DB2"
	Database vendor string for IBM Db2.

#define	ONESDK_DATABASE_VENDOR_DERBY_CLIENT "Derby Client"
	Database vendor string for JDBC connections to Apache Derby (aka. IBM Cloudscape).

#define	ONESDK_DATABASE_VENDOR_DERBY_EMBEDDED "Derby Embedded"
	Database vendor string for Derby Embedded.

#define	ONESDK_DATABASE_VENDOR_FILEMAKER "Filemaker"
	Database vendor string for FileMaker Pro.

#define	ONESDK_DATABASE_VENDOR_INFORMIX "Informix"
	Database vendor string for IBM Informix.

#define	ONESDK_DATABASE_VENDOR_INSTANT_DB "InstantDb"
	Database vendor string for InstantDB.

#define	ONESDK_DATABASE_VENDOR_INTERBASE "Interbase"
	Database vendor string for Embarcadero InterBase.

#define	ONESDK_DATABASE_VENDOR_MYSQL "MySQL"
	Database vendor string for MySQL.

#define	ONESDK_DATABASE_VENDOR_MARIADB "MariaDB"
	Database vendor string for MariaDB.

#define	ONESDK_DATABASE_VENDOR_NETEZZA "Netezza"
	Database vendor string for IBM Netezza.

#define	ONESDK_DATABASE_VENDOR_ORACLE "Oracle"
	Database vendor string for Oracle Database.

#define	ONESDK_DATABASE_VENDOR_PERVASIVE "Pervasive"
	Database vendor string for Pervasive PSQL.

#define	ONESDK_DATABASE_VENDOR_POINTBASE "Pointbase"
	Database vendor string for PointBase.

#define	ONESDK_DATABASE_VENDOR_POSTGRESQL "PostgreSQL"
	Database vendor string for PostgreSQL.

#define	ONESDK_DATABASE_VENDOR_SQLSERVER "SQL Server"
	Database vendor string for Microsoft SQL Server.

#define	ONESDK_DATABASE_VENDOR_SQLITE "sqlite"
	Database vendor string for SQLite.

#define	ONESDK_DATABASE_VENDOR_SYBASE "Sybase"
	Database vendor string for SAP ASE (aka. Sybase SQL Server, Sybase DB, Sybase ASE).

#define	ONESDK_DATABASE_VENDOR_TERADATA "Teradata"
	Database vendor string for Teradata Database.

#define	ONESDK_DATABASE_VENDOR_VERTICA "Vertica"
	Database vendor string for Vertica.

#define	ONESDK_DATABASE_VENDOR_CASSANDRA "Cassandra"
	Database vendor string for Cassandra.

#define	ONESDK_DATABASE_VENDOR_H2 "H2"
	Database vendor string for H2 Database Engine.

#define	ONESDK_DATABASE_VENDOR_COLDFUSION_IMQ "ColdFusion IMQ"
	Database vendor string for ColdFusion In-Memory Query (aka. Query of Queries).

#define	ONESDK_DATABASE_VENDOR_REDSHIFT "Amazon Redshift"
	Database vendor string for Amazon Redshift.

#define	ONESDK_DATABASE_VENDOR_COUCHBASE "Couchbase"
	Database vendor string for Couchbase.

Initialization flag constants
Flags to use with onesdk_initialize_2. See also onesdk_initialize_2
#define	ONESDK_INIT_FLAG_FORKABLE
	Do not fully initialize the SDK now but instead allow it to be used in forked child processes. More...


#define	ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME "dtdTraceTagInfo"
	Message property name for the Dynatrace byte tag. More...

#define	ONESDK_DYNATRACE_MESSAGE_PROPERTYNAME ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME
	DEPRECATED alias for ONESDK_DYNATRACE_MESSAGE_PROPERTY_NAME. More...

Messaging Destination Type Constants
See also Messaging
#define	ONESDK_MESSAGING_DESTINATION_TYPE_QUEUE 1
	A message queue: a message sent to this destination will be (sucessfully) received by only one consumer.

#define	ONESDK_MESSAGING_DESTINATION_TYPE_TOPIC 2
	A message topic: a message sent to this destination will be received by all subscribed consumers.

Messaging System Vendor Strings
See also Messaging
#define	ONESDK_MESSAGING_VENDOR_HORNETQ "HornetQ"
	Messaging system vendor string for HornetQ.

#define	ONESDK_MESSAGING_VENDOR_ACTIVE_MQ "ActiveMQ"
	Messaging system vendor string for ActiveMQ.

#define	ONESDK_MESSAGING_VENDOR_RABBIT_MQ "RabbitMQ"
	Messaging system vendor string for RabbitMQ.

#define	ONESDK_MESSAGING_VENDOR_ARTEMIS "Artemis"
	Messaging system vendor string for Artemis.

#define	ONESDK_MESSAGING_VENDOR_WEBSPHERE "WebSphere"
	Messaging system vendor string for WebSphere.

#define	ONESDK_MESSAGING_VENDOR_MQSERIES_JMS "MQSeries JMS"
	Messaging system vendor string for MQSeries JMS.

#define	ONESDK_MESSAGING_VENDOR_MQSERIES "MQSeries"
	Messaging system vendor string for MQSeries.

#define	ONESDK_MESSAGING_VENDOR_TIBCO "Tibco"
	Messaging system vendor string for Tibco.


#define	ONESDK_TRACE_ID_BUFFER_SIZE 33
	Required size for trace ID buffer (including null termiator).

#define	ONESDK_SPAN_ID_BUFFER_SIZE 17
	Required size for span ID buffer (including null termiator).

Typedefs
typedef void	onesdk_agent_logging_callback_t(char const *message)
	Agent logging function prototype. More...

typedef onesdk_int32_t	onesdk_logging_level_t
	Integer type for logging levels. More...

Handle Types

typedef onesdk_uint64_t	onesdk_handle_t
	Type for all SDK handles. More...

typedef onesdk_handle_t	onesdk_tracer_handle_t
	A handle that refers to a tracer object.

typedef onesdk_handle_t	onesdk_databaseinfo_handle_t
	A handle that refers to a database info object.

typedef onesdk_handle_t	onesdk_webapplicationinfo_handle_t
	A handle that refers to a web application info object.

typedef onesdk_handle_t	onesdk_messagingsysteminfo_handle_t
	A handle that refers to a messaging system info object.


typedef onesdk_handle_t	onesdk_metric_handle_t
	A handle that refers to a metric object.

Detailed Description

Defines common types/constants/macros. Applications should not include this file directly.

Macro Definition Documentation

◆ ONESDK_AGENT_STATE_ACTIVE

#define ONESDK_AGENT_STATE_ACTIVE 0

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

In this state...

New tracers will be created.
Data is captured and reported.
Creating "passive" objects is possible (e.g. onesdk_databaseinfo_create).

◆ ONESDK_AGENT_STATE_NOT_INITIALIZED

#define ONESDK_AGENT_STATE_NOT_INITIALIZED 3

The agent has not been initialized.

E.g. because the application didn't call onesdk_initialize, onesdk_initialize failed or the agent has already been shut down (onesdk_shutdown).

In this state...

No new tracers will be created.
No data is captured/reported.
Creating "passive" objects will also fail (e.g. onesdk_databaseinfo_create).

◆ ONESDK_AGENT_STATE_PERMANENTLY_INACTIVE

#define ONESDK_AGENT_STATE_PERMANENTLY_INACTIVE 2

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

The agent will not become active again. This can happen e.g. if the application process has been forked while the SDK was initialized and the calling process is the fork child.

The effects are the same as with ONESDK_AGENT_STATE_NOT_INITIALIZED.

◆ ONESDK_AGENT_STATE_TEMPORARILY_INACTIVE

#define ONESDK_AGENT_STATE_TEMPORARILY_INACTIVE 1

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

The agent may become active again at any time though. If your application uses the agent state to "skip" SDK calls, it should re-check the status periodically.

In this state...

No new tracers will be created.
No data is captured/reported.
Creating "passive" objects is possible though (e.g. onesdk_databaseinfo_create).

◆ ONESDK_INIT_FLAG_FORKABLE

#define ONESDK_INIT_FLAG_FORKABLE

Do not fully initialize the SDK now but instead allow it to be used in forked child processes.

When setting this flag, onesdk_initialize_2 will only partially initialize the SDK agent. 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.
onesdk_agent_get_version_string and onesdk_stub_get_agent_load_info work as expected.
onesdk_agent_get_current_state will return ONESDK_AGENT_STATE_TEMPORARILY_INACTIVE - but see the note below.
onesdk_agent_set_warning_callback and onesdk_agent_set_verbose_callback work as expected, the callback will be carried over to forked child processes.
It is recommended you call onesdk_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 onesdk_agent_get_current_state in the pre-initialized state will cause the agent to become fully initialized.

See also: onesdk_agent_get_fork_state can be used to query which of these states the agent is in.

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 onesdk_shutdown in a pre-initialized process is not required otherwise.

Note: If you use POSIX wait or similar functions, you might observe an additional child process in the original parent-initialized process.

Since: This flag requires at least agent version 1.151.

◆ ONESDK_INVALID_HANDLE

#define ONESDK_INVALID_HANDLE 0

Invalid handle value (zero).

Functions that create objects will return ONESDK_INVALID_HANDLE if the object could not be created. Passing ONESDK_INVALID_HANDLE as argument to a required parameter will usually result in a silent error. That means no warning will be logged and the function will simply do nothing.