C/C++ API ReferencePermanent link for this heading

The Fabasoft app.telemetry Software-Telemetry C/C++ API allows you to instrument any C/C++ application with instrumentation points to see what's going on in complex applications.

Constants(C/C++)Permanent link for this heading

This chapter lists the available constants to be used for instrumenting your C/C++ application.

Flags (C/C++)Permanent link for this heading

Flags are used to specify the type of an event and are passed as argument to every event call. They are predefined by the API with the data type UInt8 and have the following possible values:

  • APM_FLAG_NONE
  • APM_FLAG_ENTER
  • APM_FLAG_LEAVE
  • APM_FLAG_WAIT
  • APM_FLAG_WARNING
  • APM_FLAG_ERROR
  • APM_FLAG_PROCESS_INFO

For more details about the flags and there meaning see the general chapter “Flags”.

Log Level (C/C++)Permanent link for this heading

An event will only be logged if the event-level is lower or equal to the value selected in the session or log-definition. The log levels are predefined by the API with the data type UInt8 and have the following possible values:

  • APM_EVENT_LEVEL_LOG
  • APM_EVENT_LEVEL_IPC (only internal)
  • APM_EVENT_LEVEL_NORMAL
  • APM_EVENT_LEVEL_DETAIL
  • APM_EVENT_LEVEL_DEBUG

For more details about the log levels and there meaning see the general chapter “Log Level”.

Parameter Types (C/C++)Permanent link for this heading

Parameter types provide type information of parameters in a call to APMEventArgs (see “Method APMEventArgs (C/C++)”)

Name

Value

Description

APM_PARAMETERTYPE_INT32

1

parameter is of type UInt32

APM_PARAMETERTYPE_INT64

2

parameter is of type UInt64

APM_PARAMETERTYPE_STRING

3

parameter is an utf-8 encoded string(0 terminated)

Predefined Modules (C/C++)Permanent link for this heading

For a list of available standard modules with a set of predefined events see chapter “Standard Modules”.

Predefined Events (C/C++)Permanent link for this heading

The SDK already provides a set of predefined events used for general purpose. For a full listing of all available predefined events see the generic chapter "Predefined Events".

Error/Trace Events:

Use these standard events to mark error, warning or info conditions in your application like in the following example:

  • APM_EVENT_ERROR
  • APM_EVENT_WARNING
  • APM_EVENT_INFO
  • APM_EVENT_TRACE

Code Example

APMEventStr(anymodule, APM_EVENT_ERROR, APM_EVENT_LEVEL_NORMAL, APM_FLAG_ERROR, "My error message”);

APMEventStr(anymodule, APM_EVENT_WARNING, APM_EVENT_LEVEL_NORMAL, APM_FLAG_WARNING, "My warning message”);

APMEventStr(anymodule, APM_EVENT_INFO, APM_EVENT_LEVEL_NORMAL, APM_FLAG_NONE, "My info message”);

APMEventStr(anymodule, APM_EVENT_TRACE, APM_EVENT_LEVEL_DETAIL, APM_FLAG_ERROR, "My trace message”);

Predefined Application Property Keys and Names (C/C++)Permanent link for this heading

Key

Name

Purpose

APM_APP_PROPERTY_INSTANCE_GUID_KEY

APM_APP_PROPERTY_INSTANCE_GUID_NAME

Instance ID

Predefined Application Value Keys and Names (C/C++)Permanent link for this heading

Key

Name

Purpose

APM_APP_VALUE_VERSION_KEY

APM_APP_VALUE_VERSION_NAME

Application Version

APM_APP_VALUE_INSTANCE_NAME_KEY

APM_APP_VALUE_INSTANCE_NAME_NAME

Instance Name

Counter Attributes (C/C++)Permanent link for this heading

Counter attributes define behavior, aggregation, measurement, representation and labels of registered counters. Some of the attributes can be changed but most must be defined during the initial counter registration.

Name

Description

Type

APM_COUNTER_ATTRIBUTE_NONE

End marker for attribute definition lists.

-

APM_COUNTER_ATTRIBUTE_GROUP_DISPLAY_NAME

Group display name of the counter.

Pointer

APM_COUNTER_ATTRIBUTE_DISPLAY_NAME

Display name of the counter.

Pointer

APM_COUNTER_ATTRIBUTE_INSTANCE_NAME

Name of the counter instance.

Pointer

APM_COUNTER_ATTRIBUTE_INSTANCE_DISPLAY_NAME

Instance display name of the counter.

Pointer

APM_COUNTER_ATTRIBUTE_DATA_SIZE

Length of the memory buffer for String values.

Number

APM_COUNTER_ATTRIBUTE_CALLBACK

APMCounterCallback structure address.

Pointer

APM_COUNTER_ATTRIBUTE_MEASUREMENT_INTERVAL

Interval (in Seconds) of automatic counter recording.

Number

APM_COUNTER_ATTRIBUTE_AGGREGATION_FUNCTION_NAME

See APM_COUNTER_AGGREGATION_FUNCTION_* constants.

Pointer

APM_COUNTER_ATTRIBUTE_APPLICATION

APMApplicationHandle of the application that owns the counter.

Number

APM_COUNTER_ATTRIBUTE_BASE

Base for fractional counter values.

Number

APM_COUNTER_ATTRIBUTE_WARNING_LIMIT

Warning limit for service check, related to the service check property “warning”, given as string.

Pointer

APM_COUNTER_ATTRIBUTE_ERROR_LIMIT

Critical limit for service check, related to the service check property “error”, given as string.

Pointer

Remarks:

The two attributes APM_COUNTER_ATTRIBUTE_WARNING_LIMIT and APM_COUNTER_ATTRIBUTE_ERROR_LIMIT are available with Version 2021 UR 1. Use them to automatically configure a corresponding service check with „warning“ and „error“ property as given, like in the following examples:

Attribute

Value

Service Check

APM_COUNTER_ATTRIBUTE_WARNING_LIMIT

“80”

The status of the service check is “Warning” if the value of the counter is above 80.

APM_COUNTER_ATTRIBUTE_ERROR_LIMIT

“::90”

The status of the service check is “Critical” if the value of the counter is below 90.

APM_COUNTER_ATTRIBUTE_WARNING_LIMIT

“10::20[15]”

The status of the service check is “Warning” if the value of the counter is above 10 and below 20 for a duration of 15 seconds.

APM_COUNTER_ATTRIBUTE_ERROR_LIMIT

“error”

The status of the service check is “Critical” if the text of the counter matches “error” (for Counter Type APM_COUNTER_DATATYPE_TEXT).

Counter Types (C/C++)Permanent link for this heading

Name

Description

APM_COUNTER_TYPE_RAW

Raw counter without special interpretation.

APM_COUNTER_TYPE_COUNTER

Per second values.

APM_COUNTER_TYPE_FRACTION

Percent value.

Counter Datatypes (C/C++)Permanent link for this heading

Name

Description

APM_COUNTER_DATATYPE_UINT32

32-Bit Unsigned Integer

APM_COUNTER_DATATYPE_UINT64

64-Bit Unsigned Integer

APM_COUNTER_DATATYPE_TEXT

UTF-8 Encoded Text

Aggregation Function Names (C/C++)Permanent link for this heading

Name

Description

APM_COUNTER_AGGREGATION_FUNCTION_SUM

Sum

APM_COUNTER_AGGREGATION_FUNCTION_AVG

Average

APM_COUNTER_AGGREGATION_FUNCTION_MAX

Maximum

APM_COUNTER_AGGREGATION_FUNCTION_MIN

Minimum

Data types (C/C++)Permanent link for this heading

APMApplicationHandle (C/C++)Permanent link for this heading

APMApplicationHandle is used to identify an application registered in your process by calling APMRegisterApplication (see “Method APMRegisterApplication (C/C++)”). The handle is only valid in the same process until you call APMUnregisterApplication (see “Method APMUnregisterApplication (C/C++)”)

Type Declaration

typedef UInt32 APMApplicationHandle;

APMModuleHandle (C/C++)Permanent link for this heading

APMModuleHandle is used to identify a module registered in your process by calling APMRegisterModule (see “Method APMRegisterModule (C/C++)”). The handle is valid only in the same process until you call APMUnregisterModule (see “Method APMUnregisterModule (C/C++)”).

Type Declaration

typedef UInt32 APMModuleHandle;

APMCounterHandle (C/C++)Permanent link for this heading

APMCounterHandle is used to identify a counter or counter instance registered using APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”).

Type Declaration

typedef uint32_t APMCounterHandle;

APMCounterAttributeType (C/C++)Permanent link for this heading

APMCounterAttributeType is used to identify which attribute is described by the encompassing APMCounterAttribute structure. See “Counter Attributes (C/C++)” for valid values.

Type Declaration

typedef uint32_t APMCounterAttributeType;

APMCounterType (C/C++)Permanent link for this heading

APMCounterType specifies the type of the counter registered using APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”). See 2.1.9 "Counter Types (C/C++)" for a list of valid values.

Type Declaration

typedef uint8_t APMCounterType;

APMCounterDataType (C/C++)Permanent link for this heading

APMCounterDataType specifies the data-type of the counter registered using APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”). See “Counter Datatypes (C/C++)” for a list of valid values.

Type Declaration

typedef uint8_t APMCounterDataType;

APMCounterAttribute (C/C++)Permanent link for this heading

APMCounterAttribute is used to pass attributes to the registration function APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”).

Type Declaration

typedef struct {
  APMCounterAttributeType attributeType;
  int64_t value;
  const void *pointer;
} APMCounterAttribute;

APMCounterCallback (C/C++)Permanent link for this heading

APMCounterCallback is used to pass a counter callback with optional custom data to the APMRegisterCounter (see “Method APMRegisterCounter (C/C++)”) function via the attributes as an APM_COUNTER_ATTRIBUTE_CALLBACK.

Type Declaration

typedef struct {
  void (*function)(void*);
  void *data;
} APMCounterCallback;

APMEventId (C/C++)Permanent link for this heading

APMEventId is used to identify an event. The event id must be unique per module and you are free to choose a value. Avoid using predefined event ids (see Predefined Events (C/C++)).

APMEventId is declared as:

Type Declaration

typedef UInt64 APMEventId;

APMEventLevel (C/C++)Permanent link for this heading

APMEventLevel is used to specify the importance of an event.

Type Declaration

typedef UInt8  APMEventLevel;

Possible values are:

  • APM_EVENT_LEVEL_LOG
  • APM_EVENT_LEVEL_IPC
  • APM_EVENT_LEVEL_NORMAL
  • APM_EVENT_LEVEL_DETAIL
  • APM_EVENT_LEVEL_DEBUG

APMEventFlags (C/C++)Permanent link for this heading

APMEventFlags is used to specify the type of an event.

Type Declaration

typedef UInt8  APMEventFlags;

Possible values are:

  • APM_FLAG_NONE
  • APM_FLAG_ENTER
  • APM_FLAG_LEAVE
  • APM_FLAG_WAIT
  • APM_FLAG_WARNING
  • APM_FLAG_ERROR

APMParameterType (C/C++)Permanent link for this heading

APMParameterType is used to specify the type of the parameter (see “Method APMEventArgs (C/C++)”).

Code Definition

typedef UInt8  APMParameterType;

Possible values are:

  • APM_PARAMETERTYPE_INT32
  • APM_PARAMETERTYPE_INT64
  • APM_PARAMETERTYPE_STRING

EnumAppFilterValuesCallback (C/C++)Permanent link for this heading

Applications may register a callback when calling APMRegisterApplication (see Method APMRegisterApplication (C/C++)”). The callback should enumerate all valid filter values by repeatedly calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”) to register all valid values, that may be selected when starting a Software-Telemetry session. The callback will be triggered by the app.telemetry server, if no filter values are defined for the registered application or once per hour to refresh the values.

Code Definition

typedef void (APMFUNC *EnumAppFilterValuesCallback)();

APMContext (C/C++)Permanent link for this heading

Values of type APMContext need to be passed during inter-process communication to provide the caller context to the invoked program (see “Method APMGetContext (C/C++)” and “Method APMAttachContext (C/C++)”).

Code Definition

typedef unsigned char APMContext[16];

APMSyncMark (C/C++)Permanent link for this heading

Values of type APMSyncMark need to be passed during inter-process communication to provide time sequence information (see “Method APMGetSyncMark (C/C++)” and “Method APMSetSyncMark (C/C++)”).

Code Definition

typedef unsigned char APMSyncMark[16];

APMParamHandle (C/C++)Permanent link for this heading

Pointers of type APMParamHandle are used to register multiple parameters for use with APMEventParam (see “Method APMEventParam (C/C++)” and “Parameter Functions (C/C++)”).

Code Definition

typedef void *APMParamHandle;

Registration Functions (C/C++)Permanent link for this heading

Method APMRegisterApplication (C/C++)Permanent link for this heading

Call this function once to provide information about the context of the application.

Syntax

APMDECL_EXTERN APMApplicationHandle APMFUNC APMRegisterApplication(
    const char *app
Name,
    const char *app
Id,
    const char *app
TierName,
    const char *app
TierId,
    EnumAppFilter
ValuesCallback filterCallback);

Parameters:

  • appName: The name of your application (utf-8 encoded)
  • appId: The Id of your application (utf-8 encoded)
  • appTierName: The tier inside the application (utf-8 encoded)
  • appTierId: Id to distinguish multiple services of one application tier (utf-8 encoded)
  • filterCallback: A callback for filter registration

Return Value:

  • This function returns the application handle of the registered application.

Remarks:

Your application must be registered before any events can be fired.

Usage Example

void RegisterSoftwareTelemetry()
{

  APMApplicationHandle g_applicationHandle = APMRegisterApplication(

    
"app.telemetry Software-Telemetry", "Demo", // appName, appId
    
"Backend Services”, "Repository",           // appTierName, -Id
    
NULL);                                      // filterCallback
}

Method APMRegisterApplicationProperty (C/C++)Permanent link for this heading

Call APMRegisterApplicationProperty to register additional application registration properties immediately after you call to APMRegisterApplication to ensure proper operation.

Syntax

APMDECL_EXTERN void APMFUNC APMRegisterApplicationProperty(
    APMApplicationHandle application,

   const char *propertyKey,
    const char *
propertyName,
    const char *
propertyValue);

Parameters:

  • application: The handle of the application for which you are registering additional registration properties.
  • propertyKey: The application defined key of the property or the predefined APM_APP_PROPERTY_INSTANCE_GUID_KEY (utf-8 encoded). Limited to 256 Bytes. Keys starting with “apm:” are reserved for internal use.
  • propertyName: The display name of the property (utf-8 encoded) (APM_APP_PROPERTY_INSTANCE_GUID_NAME for the example above). Limited to 512 Bytes.
  • propertyValue: The value of the property (utf-8 encoded). Limited to 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

Application registration properties cannot be changed after they have been set.

Usage Example

void RegisterSoftwareTelemetryGUID()
{

  APMApplicationHandle g_applicationHandle = APMRegisterApplication(

    "app.telemetry Software-Telemetry", "Demo", // app
Name, appId
    "Backend Services”, "Repository",           // app
TierName, -Id
    NULL);                                      // filterCallback

  APMRegisterApplicationProperty(g_
applicationHandle,
    
APM_APP_PROPERTY_INSTANCE_GUID_KEY,
    
APM_APP_PROPERTY_INSTANCE_GUID_NAME,
    
"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"); // unique for every instance of this application globally.
}

void RegisterSoftwareTelemetryCustom()
{

  APMApplicationHandle g_applicationHandle = APMRegisterApplication(

    "app.telemetry Software-Telemetry", "Demo", // app
Name, appId
    "Backend Services”, "Repository",           // app
TierName, -Id
    NULL);                                      // filterCallback

  APMRegisterApplicationProperty(g_
applicationHandle,
    
"custom:customerId", // used internally and through APIs
    
"Customer ID", // displayed as name in the app.telemetry UI
    
"132456789");  // displayed as the value in the app.telemtry UI
}

Method APMRegisterApplicationValue (C/C++)Permanent link for this heading

Call APMRegisterApplicationValue to register additional static information about your application such as the version number or the display name of this globally unique instance.

Syntax

APMDECL_EXTERN void APMFUNC APMRegisterApplicationValue(
    APMApplicationHandle application,

   const char *valueKey,
    const char *
valueName,
    const char *
value);

Parameters:

  • application: The handle of the application for which you are registering additional registration properties.
  • valueKey: The application defined key of the value or one of the predefined (APM_APP_VALUE_VERSION_KEY, APM_APP_VALUE_INSTANCE_NAME_KEY, …) (utf-8 encoded). Limited to 256 Bytes. Keys starting with “apm:” are reserved for internal use.
  • valueName: The display name of the property (utf-8 encoded) (APM_APP_VALUE_VERSION_NAME, APM_APP_VALUE_INSTANCE_NAME_NAME,… for the examples above). Limited to 512 Bytes.
  • value: The value of the property (utf-8 encoded). Limited to 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

Application values may be changed at runtime but must not have a high change frequency and do not have any history of previous values.

Usage Example

void RegisterSoftwareTelemetry()
{

  APMApplicationHandle g_applicationHandle = APMRegisterApplication(

    "app.telemetry Software-Telemetry", "Demo", // app
Name, appId
    "Backend Services”, "Repository",           // app
TierName, -Id
    NULL);                                      // filterCallback

  APMRegisterApplication
Property(g_applicationHandle,
    APM_APP_PROPERTY_INSTANCE_GUID_KEY,
    
APM_APP_PROPERTY_INSTANCE_GUID_NAME,
    
"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"); // unique for every instance of this application globally.
  APMRegisterApplicationValue(g_applicationHandle,

    
APM_APP_VALUE_VERSION_KEY,
    
APM_APP_VALUE_VERSION_NAME,
    
"18.3.21");
  APMRegisterApplicationValue(g_applicationHandle,

    
APM_APP_VALUE_INSTANCE_NAME_KEY,
    
APM_APP_VALUE_INSTANCE_NAME_NAME,
    
"Customer X Index Service 1 for E-Mail");
}

Method APMUnregisterApplication (C/C++)Permanent link for this heading

Call APMUnregisterApplication at the end of your program to tell app.telemetry agent that your program lifetime ends now.

Syntax

APMDECL_EXTERN void APMFUNC APMUnregisterApplication(APMApplicationHandle application);

Parameters:

  • application: The handle of the application which gets unregistered.

Return Value:

This function does not return any value.

Remarks:

Unregistering all applications will stop the connection to the app.telemetry agent. As reconnecting takes time it is not recommended to unregister and reregister applications frequently.

Usage Example

void UnregisterSoftwareTelemetry()
{

    APMUnregisterAppl
ication(g_applicationHandle);
}

Method APMRegisterModule (C/C++)Permanent link for this heading

Call this function to register modules inside your application.

Syntax


APMDECL_EXTERN APMModuleHandle APMFUNC APMRegisterModule(

    
const char *modulename);

Parameters:

  • modulename Desired name of the APMModule (utf-8 encoded).

Return Value:

  • This function returns a handle which you need to associate events to their corresponding module.

Remarks:

  • Different modules are shown as different bars during the analysis.
  • Modules are registered per process and not per application, so each application in a process can use modules registered one in that process.
  • Modules are identified by their name. A registration of a module with a previously registered module name will return the same module handle as the first module registration as long as the module has not been unregistered.

Usage Example

//define constants for your events
#define APM_EVENT_PROCESS_REQUEST  100

#define APM_EVENT_GET_ARTICLE      101

#define APM_EVENT_GET_ARTICLE_DATA 102

APMApplicationHandle g_applicatione;
APMModuleHandle g_module;

void RepositoryRegisterEvents()
{

  
  APMModuleRegisterEvent(g_module, APM_EVENT_PROCESS_REQUEST, "Process Request", NULL);
  
  APMModuleRegisterEvent(g_module, APM_EVENT_GET_ARTICLE, "Get Article", NULL);
    APMModuleRegisterEvent(g_module, APM_EVENT_GET_ARTICLE_DATA, "GetArticle::length", "length(bytes)");
}

void RegisterSoftwareTelemetry()
{

    g_module = APMRegisterModule("Repository Handler");
  
  RepositoryRegisterEvents();
}

Method APMUnregisterModule (C/C++)Permanent link for this heading

Call APMUnregisterModule if you do not need to trace any more events tied with this module. Calling this function will clean up several internal processes.

Syntax

APMDECL_EXTERN void APMFUNC APMUnregisterModule(APMModuleHandle module);

Parameters:

  • module: Handle to the module which should get unregistered

Return Value:

This function does not return any value.

Remarks:

You may register and unregister modules any time but you should not reregister a single module frequently as the app.telemetry server has to keep all module registrations to be able to display all requests of a process correctly.

Usage Example

void CleanupModule(APMModuleHandle module)
{

  APMUnregisterModule(module);
}

Method APMModuleRegisterEvent (C/C++)Permanent link for this heading

It is required and important to register the events used in your application in order to get the correct event names and parameter descriptions as provided. The APMModuleRegisterEvent-function will tell the app.telemetry server a name for every event-ID and optionally parameter descriptions for the parameters used in the event calls.

Syntax

APMDECL_EXTERN void APMFUNC APMModuleRegisterEvent(
    APMModuleHandle module,

    APMEventId eventid,

    const char *description,

    const char *parameterdescription);

Parameters:

  • module: Module handle for which you register the event.
  • eventid: This is the id of the event you want to register.
  • description: The description of the event.
  • parameterdescription: Name of event parameters. If more parameters are used in one event, separate the parameter names by semi-colon (;). For example: "name;count;size"

Return Value:

This function does not return any value.

Remarks:

If an event has more than one parameter you need to separate the parameterdescription with semicolons (;).

Usage Example

void doRegisterEvents()
{

    //given that g_module is a valid handle of a registered module
  
  APMModuleRegisterEvent(g_module, 121, "Event 1", "int32;int64;String");
    APMModuleRegisterEvent(g_module, 122, "Event 2", "size;time stamp;User name");
}

Method APMRegisterFilterValue (C/C++)Permanent link for this heading

It is useful to register all possible filter values used in your application in order to get a list of available filters with descriptions in the client interface.

You may actively register filter values any time after registering the application by calling the APMRegisterFilterValue method.

To optimize filter registration in case enumeration of filter values is a costly action, the registration of filter values may be performed in the EnumAppFilterValuesCallback function, which is only called if needed (see “EnumAppFilterValuesCallback (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMRegisterFilterValue(
  
APMApplicationHandle app,
    const char *value,

    const char *description);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • value: value is the raw filter value.
  • description: This is the description which is presented in the Client-User-Interface as filter.

Return Value:

This function does not return any value.

Remarks:

This function may be called inside the EnumAppFilterValuesCallback function which is initiated by the app.telemetry server.

Usage Example

void EnumAppFilterValuesCallback()
{

    APMRegisterFilterValue(g_applicationHandle, "raw filter 1", "Description for filter 1");
}

Method APMRegisterCounter (C/C++)Permanent link for this heading

Call APMRegisterCounter once for every counter or counter instance to make the counter known to the app.telemetry library for collection.

Syntax

APMDECL_EXTERN APMCounterHandle APMFUNC APMRegisterCounter(
  const char *utf8GroupName,
  const char *utf8CounterName,
  APMCounterType counterType,
  APMCounterDataType counterDataType,
  const void *dataAddress,
  const APMCounterAttribute *counterAttributes);

Parameters:

  • utf8GroupName: The group name of the counter (utf-8 encoded) Note: Group names starting with “apm” are reserved for internal use and must not be used by application developers.
  • utf8CounterName: The name of the counter (utf-8 encoded).
  • counterType: The counter type, see Counter Types (C/C++)
  • counterDataType: The counter data type, see Counter Datatypes (C/C++).
  • dataAddress: The address from which the counter value can be read the number of bytes fetched depends on the datatype of the counter.
  • counterAttributes: List of APMCounterAttribute structures with an end marker (APM_COUNTER_ATTRIBUTE_NONE) that define additional counter attributes, see Counter Attributes (C/C++) for a list of supported attributes.
  • Return Value:
  • This function returns the handle to the counter that can be used to change some attributes and unregister the counter.

Usage Example

static uint32_t g_availableThreadCounter = 0;
void
UpdateAvailableThreadCounter(void *data)
{

  g
_availableThreadCounter = someCalculation();
}

void RegisterCounters()
{

  const APMCounterCallback callback = {
UpdateAvailableThreadCounter, nullptr, };
  const APMCounterAttribute attributes[] = {
    { APM_COUNTER_ATTRIBUTE_GROUP_DISPLAY_NAME, 0, "Scheduler", },
    { APM_COUNTER_ATTRIBUTE_DISPLAY_NAME, 0, "Threads Available", },
    { APM_COUNTER_ATTRIBUTE_DISPLAY_SUFFIX, 0, "#", },
    { APM_COUNTER_ATTRIBUTE_MEASUREMENT_INTERVAL, 10, nullptr, },
    { APM_COUNTER_ATTRIBUTE_AGGREGATION_FUNCTION_NAME, 0, APM_COUNTER_AGGREGATION_FUNCTION_MIN, },
    { APM_COUNTER_ATTRIBUTE_CALLBACK, 0, &callback, },
    { APM_COUNTER_ATTRIBUTE_APPLICATION, applicationHandle, nullptr, },
    { APM_COUNTER_ATTRIBUTE_NONE, 0, nullptr, },
  };
  g_numIdleThreadsCounterHandle = APMRegisterCounter("fsc.Scheduler", "numAvailableThreads", APM_COUNTER_TYPE_RAW, APM_COUNTER_DATATYPE_UINT32, &g_availableThreadCounter, attributes);
}

Method APMUpdateCounterAttributes (C/C++)Permanent link for this heading

Call APMUpdateCounterAttributes to update some attributes of a registered counter. Note: Only the listed attributes can be updated using this function.

Syntax

APMDECL_EXTERN void APMFUNC APMUpdateCounterAttributes(
  APMCounterHandle counterHandle,
  const APMCounterAttribute *counterAttributes);

Parameters:

  • counterHandle: The handle of a registered counter whose attributes need to be updated.
  • counterAttributes: List of APMCounterAttribute structures with an end marker (APM_COUNTER_ATTRIBUTE_NONE) that define attributes to be updated.

Supported Attributes:

  • APM_COUNTER_ATTRIBUTE_GROUP_DISPLAY_NAME
  • APM_COUNTER_ATTRIBUTE_DISPLAY_NAME
  • APM_COUNTER_ATTRIBUTE_INSTANCE_DISPLAY_NAME

Return Value:

This function does not return any value.

Usage Example

void UpdateCounters()
{

  
const APMCounterAttribute idleThreadsAttributes[] = {
    { APM_COUNTER_ATTRIBUTE_DISPLAY_NAME, 0, "New Display Name", },
    { APM_COUNTER_ATTRIBUTE_NONE, 0, nullptr, },
  };
  
APMUpdateCounterAttributes(g_numIdleThreadsCounterHandle, idleThreadsAttributes);
  const APMCounterAttribute indexedDocumentsAttributes[] = {
    { APM_COUNTER_ATTRIBUTE_INSTANCE_DISPLAY_NAME, 0, "Fileshare /mnt/xxx", },
    { APM_COUNTER_ATTRIBUTE_NONE, 0, nullptr, },
  };
  
APMUpdateCounterAttributes(g_numIndexedDocumentsCounterHandle1, indexedDocumentsAttributes);
}

Method APMUnregisterCounter (C/C++)Permanent link for this heading

Call APMUnregisterCounter to unregister a previously registered counter to free it’s associated resources and stop any collection.

Syntax

APMDECL_EXTERN void APMFUNC APMUnregisterCounter(
  APMCounterHandle counterHandle);

Parameters:

  • counterHandle: The handle of a registered counter that will be unregistered.
  • Return Value:
  • This function does not return any value.

Usage Example

void UnregisterCounters()
{

  APMUnregisterCounter(g_numIdleThreadsCounterHandle;
  
APMUnregisterCounter(g_numIndexedDocumentsCounterHandle1);
}

Context Handling Functions (C/C++)Permanent link for this heading

Method APMCreateContext (C/C++)Permanent link for this heading

Call APMCreateContext to create a new Software-Telemetry context. If the filter value matches a currently started session filter, logging is started for the current execution thread. Make sure to call APMReleaseContext when exiting the context. A context can be regarded as a complete request that is traced through several involved threads or modules. And the full context request has a duration that spans the interval from CreateContext to ReleaseContext.

Syntax

APMDECL_EXTERN void APMFUNC APMCreateContext(APMApplicationHandle app, const char *filtervalue);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • filtervalue: (optional) This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”)

Return Value:

This function does not return any value.

Usage Example

void beginRequestProcessing(/* ... */)
{

  
  APMCreateContext(g_applicationHandle, "filter1");
    //...
  
  //proceed with application logic and fire events
    //...
  
  APMReleaseContext();
}

Method APMAttachContext (C/C++)Permanent link for this heading

Call APMAttachContext to restore the context acquired through APMGetContext in another thread or process (see “Passing Context” and “Method APMGetContext (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMAttachContext(APMApplicationHandle app, const APMContext *context);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • context: The context which you want to attach to.

Return Value:

This function does not return any value.

Usage Example

void ContinueRequest(/* ... */, const APMContext *context, APMSyncMark *syncMark)
{

    APMAttachContext(g_applicationHandle, context);

    //...
    // continue with application logic and fire events

    //...
    APMGetSyncMark(syncMark);

    APMReleaseContext();

}

Method APMGetContext (C/C++)Permanent link for this heading

Call the APMGetContext-method to get a new context handle.

This context handle is used to synchronize different threads/processes/modules - this helps you track the control flow through a distributed environment. The acquired context handle has to be submitted (either by transmitting over the network or in another way) to the thread/process being called which associates the calling thread with itself by passing the context to the APMAttachContext-method.

Syntax

APMDECL_EXTERN int APMFUNC APMGetContext(APMContext *context);

Parameters:

  • context: APMGetContext creates a context at the location pointed to by context.

Return Value:

  • If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
  • If no context has been created, the return value is 0.

Usage Example

void initiateProcessing(/* ... */)
{

    APMCreateContext(g_applicationHandle, "filterstring");

    APMContext contex
t;
    APMGetContext(&context);

    //pass context to another thread, process on the same or a remote machine

   doRemote(/* data */, context);

    //do some local processing / wait for the remote processing to complete

    APMSyncMark syncMark;
    getRemoteResult(&syncMark);

    APMSetSyncMark(&syncMark);

    APMReleaseContext();

}

Method APMGetSyncMark (C/C++)Permanent link for this heading

Call the APMGetSyncMark-method to get a synchronization handle that can be passed to another thread/process/module to synchronize control flow.

The difference between a sync mark and a context is:

  • A context is used to associate with one request. It is created by the initiator and attached to by other threads/process belonging to the same request.
  • A sync mark is only a time synchronization handle between the different threads/processes which can be used several times to synchronize the control flow exactly (different systems may have different timestamps and different time precision).

Syntax

APMDECL_EXTERN int APMFUNC APMGetSyncMark(APMSyncMark *context);

Parameters:

  • context: APMGetSyncMark creates a sync mark at the location pointed to by context.

Return Value:

  • If the function succeeds, the return value is 1 and a sync mark has been saved to the location which context pointed to.
  • If no sync-mark has been created, the return value is 0.

Usage Example

void doRemote(/* ... */, APMContext *context)
{

    APMAttachContext
(g_applicationHandle, context);

    //application logic, events, ...

    APMSyncMark syncMark;
    APMGetSyncMark(&syncMark);

    sendResultBack(/* ... */, syncMark);

    APMReleaseContext();

}

Method APMSetSyncMark (C/C++)Permanent link for this heading

Call APMSetSyncMark to pass a sync mark you got from APMGetSyncMark for synchronizing the sequence of events (see “Synchronizing Timeline with SyncMarks” and “Method APMGetSyncMark (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMSetSyncMark(const APMSyncMark *context);

Parameters:

  • context: The sync mark which you want to sync with.

Return Value:

This function does not return any value.

Usage Example

void initiateProcessing(/* ... */)
{

  
  APMCreateContext(g_applicationHandle, "filterstring");
  
  APMContext context;
  
  APMGetContext(&context);

    //pass context to another thread, process or a remote server

    doRemote(/* data */, context);

    //do some local processing/wait for the remote processing to complete
    APMSyncMark syncMark;
  
  getRemoteResult(&syncMark);
    APMSetSyncMark(&syncMark);
  
  APMReleaseContext();
}

Method APMReleaseContext (C/C++)Permanent link for this heading

Call APMReleaseContext to finish logging and to flush logged information to the app.telemetry infrastructure.
Make sure to call APMReleaseContext when exiting the context (when the request is finished).

Syntax

APMDECL_EXTERN void APMFUNC APMReleaseContext();

Parameters:

This function does not take any arguments.

Return Value:

This function does not return any value.

Remarks:

  • If you don't call APMReleaseContext the request keeps the running status until the request-timeout has been reached.

Usage Example

void doRemote(/* ... */, APMContext *context)
{

  APMAttachContext(g_applicationHandle, context);

  //application logic, events, ...

  APMSyncMark syncMark;

  APMGetSyncMark(&syncMark);

  sendResultBack(/* ... */, syncMark);

  APMReleaseContext();

}

Method APMDetachThread (C/C++)Permanent link for this heading

Call the APMDetachThread-method when processing of a particular request is suspended and will be resumed later in this or another thread in the same process. Pass the handle returned by this method to the APMAttachThread-method to resume processing.

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the APMDetach-/APMAttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Syntax

APMDECL_EXTERN int APMFUNC APMDetachThread(APMTransactionHandle *handle);

Parameters:

  • handle: APMDetachThread generates an id (64bit) that uniquely identifies the current state of the request.

Return Value:

  • If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
  • The function will return 0 in case the library is not available or if no request has been started using APMCreateContext and/or APMAttachContext.

Remarks:

Be careful to use APMDetachThread and APMAttachThread in a balanced way. APMDetachThread will store the current state of the request in memory and APMAttachThread will remove the information from memory while restoring the request state. So calls to APMDetachThread lacking a continuation will leak memory and will leave the request in a "running" state. Multiple calls to APMAttachThread with the same handle will not have an effect, because the request state is only available to the first call to APMAttachThread.

Usage Example

struct TaskData
{

  
//...
  
  APMTransactionHandle tx;
  
  //...
}

void initiateProcessing(/* ... */)
{

    APMCreateContext(g_applicationHandle, "filterstring");

    TaskData *task = new TaskData();

    APMEvent(myModule, APM_EVENT_ENTER_TASK_TO_QUEUE, APM_EVENT_LEVEL_NORMAL, APM_FLAG_ENTER);

    APMDetachThread(&task->tx);

    queueTask(task);

}

void processTask(TaskData *task)
{
    APMAttachThread(task->tx);

    APMEvent(myModule, APM_EVENT_REMOVE_TASK_FROM_QUEUE, APM_EVENT_LEVEL_NORMAL, APM_FLAG_LEAVE);

    // process work

    delete task;
    APMReleaseContext();

}

Method APMAttachThread (C/C++)Permanent link for this heading

Call the APMAttachThread-method when processing of a particular request is resumed after being suspended in this or another thread of the same process. Pass the handle returned by APMDetachThread-method to restore the recorded state of the request.

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the Detach-/AttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Syntax

APMDECL_EXTERN void APMFUNC APMAttachThread(APMTransactionHandle handle);

Parameters:

  • handle: APMAttachThread uses the handle generated by APMDetachThread to identify the current state of the request.

Remarks:

See “Method APMDetachThread (C/C++)

Usage Example

struct TaskData
{

  
//...
  
  APMTransactionHandle tx;
  
  //...
}

void initiateProcessing(/* ... */)
{

    APMCreateContext(g_applicationHandle, "filterstring");

    TaskData *task = new TaskData();

    APMEvent(myModule, APM_EVENT_ENTER_TASK_TO_QUEUE, APM_EVENT_LEVEL_NORMAL, APM_FLAG_ENTER);

    APMDetachThread(&task->tx);

    queueTask(task);

}

void processTask(TaskData *task)
{

    APMAttachThread(task->tx);

    APMEvent(myModule, APM_EVENT_REMOVE_TASK_FROM_QUEUE,
APM_EVENT_LEVEL_NORMAL, APM_FLAG_LEAVE);

    // process work

    delete task;
    APMReleaseContext();

}

Event Functions (C/C++)Permanent link for this heading

The four APMEvent functions log Software-Telemetry data. They have the first 4 parameters in common and vary in the options to pass additional parameters.

The common parameters are:

Method APMEvent (C/C++)Permanent link for this heading

Call the APMEvent function to log an event without parameters. Only the event-ID and the flags define the representation of the event that will be displayed with the registered event name for the used id.

Syntax

APMDECL_EXTERN void APMFUNC APMEvent(
    APMModuleHandle module,

    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags);

Parameters:

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMEvent(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE);

    //...

Method APMEventArgs (C/C++)Permanent link for this heading

Use APMEventArgs to log an event with various parameters, which must be passed in a predefined format.

Syntax

APMDECL_EXTERN void APMFUNC APMEventArgs(
    APMModuleHandle module,

    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags,

    UInt8 paramCount,

    APMParameterType *paramTypes,

    void *paramValues,

    unsigned paramValueSize);

Parameters:

  • The APMEventArgs function has the four base parameters (see “Event Functions (C/C++)”).
  • paramCount: The number of parameters you want to pass to this function.
  • paramTypes: This is an array containing the types of the parameters. The size of the array is equal to paramCount.
  • paramValues: This pointer points to the continuous memory region containing the parameters.
  • paramValueSize: This is the size of the memory region containing the parameter values (paramValues).

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParameterType types[3] = {APM_PARAMETERTYPE_INT32,

        APM_PARAMETERTYPE_INT64, APM_PARAMETERTYPE_STRING};

    UInt32 par32 = 4;
    UInt64 par64 = 2147483698004;

    char parstr[] = "genericParam4";

    unsigned int size = (unsigned int)(sizeof(UInt32) + sizeof(UInt64) + sizeof(UInt16) + strlen(parstr));

    void *mem = calloc(1, size);
    if(mem) {

      char *bptr = (char *)(mem);

      *(UInt32 *)(bptr) = par32;

      bptr += sizeof(UInt32);

      *(UInt64 *)(bptr) = par64;

      bptr += sizeof(UInt64);

      *(UInt16 *)(bptr) = (UInt16)strlen(parstr);

      bptr += sizeof(UInt16);

      strncpy(bptr, parstr, strlen(parstr));

      APMEventArgs(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, 3, types, mem, size);
      free(mem);

    }

    //...

Method APMEventParam (C/C++)Permanent link for this heading

Call the APMEventParam-method to log events with a generic parameter structure - with any number and combination of textual (string) values and integer values (32- and 64-bit).
To use the APMEventParam-method you have to initialize an APMParamHandle. With a few helper methods you can add values to this parameter object (see “Parameter Functions (C/C++)”) and use the parameter object in the event function to be logged. Do not forget to free the parameter handle with APMParamFree (see “Method APMParamFree (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMEventParam(APMModuleHandle module,
    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags,

    APMParamHandle param);

Parameters:

  • The APMEventParam function has the four base parameters (see “Event Functions (C/C++)”).
  • param: This is the handle you obtained from a call to APMParamInit.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParamHandle ph;

    ph = APMParamInit();

    APMParamAdd32(ph, 3);

    APMParamAdd64(ph, 2147483698003);

    APMParamAddString(ph, "genericParam3");

    APMEventParam(module, 123, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, ph);

    APMParamFree(ph);

    //...

Method APMEventStr (C/C++)Permanent link for this heading

Use APMEventStr to log an event with an additional string value as parameter.

Syntax

APMDECL_EXTERN void APMFUNC APMEventStr(
  APMModuleHandle module,

  APMEventId eventid,

  APMEventLevel level,

  APMEventFlags flags,

  const char *param);

Parameters:

  • The APMEventStr function has the four base parameters (see “Event Functions (C/C++)”).
  • param: Pointer to null-terminated, utf8-encoded string. The maximum string length allowed is 32768 Byte.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMEventStr(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, "stringparam1");

    //...

Parameter Functions (C/C++)Permanent link for this heading

The parameter functions provide a way to pass up to 255 parameters to an APMEventParam call.

Allocate an APMParamHandle by calling APMParamInit. Add parameters calling APMParamAdd32, APMParamAdd64 or APMParamAddString. Pass the APMParamHandle to the APMEventParam function and finally call APMParamFree to free associated memory.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParamHandle ph;

    ph = APMParamInit();

    APMParamAdd32(ph, 3);

    APMParamAdd64(ph, 2147483698003);

    APMParamAddString(ph, "genericParam3");

    APMEventParam(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, ph);

    APMParamFree(ph);

    //...

Method APMParamInit (C/C++)Permanent link for this heading

APMParamInit is used to initialize an APMParamHandle.

Syntax

APMDECL_EXTERN APMParamHandle APMFUNC APMParamInit();

Parameters:

This function does not take any arguments.

Return Value:

  • This function returns a handle which you can use to add parameters and pass to APMEventParam.

Remarks:

Method APMParamAdd32 (C/C++)Permanent link for this heading

Call APMParamAdd32 to add a 32 bit unsigned integer to the parameter handle.

Syntax

APMDECL_EXTERN void APMFUNC APMParamAdd32(APMParamHandle param, UInt32 value);

Parameters:

  • param: APMParamHandle obtained from APMParamInit.
  • value: The value which you want to add.

Return Value:

This function does not return any value.

Method APMParamAdd64 (C/C++)Permanent link for this heading

Call APMParamAdd64 to add a 64 bit unsigned integer to the parameter handle.

Syntax

APMDECL_EXTERN void APMFUNC APMParamAdd64(APMParamHandle param, UInt64 value);

Parameters:

  • param: APMParamHandle obtained from APMParamInit.
  • value: The value which you want to add.

Return Value:

This function does not return any value.

Method APMParamAddString (C/C++)Permanent link for this heading

Call APMParamAddString to add a string to the parameter handle.

Syntax

APMDECL_EXTERN void APMFUNC APMParamAddString(APMParamHandle param, const char *value);

Parameters:

  • param: APMParamHandle obtained from APMParamInit.
  • value: The value which you want to add. The maximum length of the utf-8 encoded string is 32768 Byte.

Return Value:

This function does not return any value.

Method APMParamFree (C/C++)Permanent link for this heading

Call APMParamFree to release the memory allocated for the parameters created by APMParamInit.

Syntax

APMDECL_EXTERN void APMFUNC APMParamFree(APMParamHandle param);

Parameters:

  • param: APMParamHandle created by APMParamInit.

Return Value:

This function does not return any value.

Remarks:

Use this function to free internal memory associated to the parameters.

Fabasoft app.telemetry Button (C/C++)Permanent link for this heading

Method APMReport (C/C++)Permanent link for this heading

Call APMReport to create a new feedback report.

The filter value will be matched to the description using the registered filter values. Use the textual description of the feedback entered by the user or generated by the application to identify the report session later again.

If a log pool exists for the current application, the latest requests where the APMCreateContext filtervalue parameter matches the filtervalue passed to the APMReport function, will be associated with the feedback.

Syntax

APMDECL_EXTERN void APMFUNC APMReport(
    APMApplicationHandle app,

    const char *filtervalue,

    const char *reportkey,

    const char *description);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • filtervalue: filtervalue to match requests with.
  • reportkey: A key value may be generated by the calling application to associate further descriptions to a feedback. If empty, a new feedback report will be generated on each call and no further information may be attached to the feedback.
  • description: Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32768 Bytes.

Return Value:

This function does not return any value.

Remarks:

  • Since version 2009 Fall Release (4.3) the key value is used to associate further descriptions to a feedback.
  • In previous versions each call of this function had generated a new feedback report.

Usage Example

    //application logic, context created / attached
    APMReport(g_applicationHandle, "filter1", null, "Description entered by the user / application generated description");

Method APMReportValue (C/C++)Permanent link for this heading

Call APMReportValue to add a key/value pair to an existing report.

Syntax

APMDECL_EXTERN void APMFUNC APMReportValue(
    APMApplicationHandle app,

    const char *reportkey,

    const char *key,

    const char *value);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
  • key: A key describes the meaning of the value. Only one value can be associated to a single key in one report session.
  • value: Text (max. 32 kBytes).

Return Value:

This function does not return any value.

Usage Example

    //application logic, context created / attached
    APMReport(g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");

    APMReportValue(g_applicationHandle, "abc", "firstname", "John");

    APMReportValue(g_applicationHandle, "abc", "lastname", "Doe");

Method APMReportContent (C/C++)Permanent link for this heading

Call APMReportContent to associate content with an existing report.

Syntax

APMDECL_EXTERN void APMFUNC APMReportContent(
    APMApplicationHandle app,

    const char *reportkey,

    const char *filename,

    const void *data,

    UInt64      size);

Parameters:

  • app: The Handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the content with the report session.
  • filename: A filename describing the content of the file. (max. 256 Bytes)
  • data: Pointer to a binary data.
  • size: Size of the data content.

Return Value:

  • This function does not return any value.

Usage Example

    std::string xmlContent = "...";
    //application logic, context created / attached

    APMReport(g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");

    APMReportValue(g_applicationHandle, "abc", "firstname", "John");

    APMReportValue(g_applicationHandle, "abc", "lastname", "Doe");

    APMReportContent(g_applicationHandle, "abc", "parameter.xml", xmlContent.data(), xmlContent.length())

Method APMReportFile (C/C++)Permanent link for this heading

Call APMReportFile to associate a file with an existing report.

Syntax

  APMDECL_EXTERN void APMFUNC APMReportFile(
    APMApplicationHandle app,

    const char *reportkey,

    const char *filename,

    FILE *filehandle);

Parameters:

  • app: The handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
  • filename: A filename describing the content of the file. (max. 256 Bytes)
  • filehandle: File pointer that has been opened for reading.

Return Value:

This function does not return any value.

Remarks:

  • Until version 2010 Spring Release the filhandle has been declared as HANDLE under Microsoft Windows. This has been changed to a FILE pointer for consistency and dependency reasons since version 2010 Summer Release.

Usage Example

    //application logic, context created / attached
    APMReport(g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");

    APMReportValue(g_applicationHandle, "abc", "firstname", "John");

    APMReportValue(g_applicationHandle, "abc", "lastname", "Doe");

    FILE *f = fopen("/tmp/parameter.xml", "r");

    APMReportFile(g_applicationHandle, "abc", "parameters.xml", f);

    fclose(f);

Status Functions (C/C++)Permanent link for this heading

Method APMHasActiveContext (C/C++)Permanent link for this heading

Call APMHasActiveContext to test if a software-telemetry session is active for some logging level. This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Syntax

APMDECL_EXTERN int APMFUNC APMHasActiveContext(APMEventLevel level);

Parameters:

  • level: The event level of the event you prepare parameters for.

Return Value:

  • The return value is non-zero if the event will be logged.

Usage Example

void processRequest()
{

    APMCreateContext(g_applicationHandle, "filter value");

    //application logic

    if (0 != APMHasActiveContext(APM_EVENT_LEVEL_DEBUG))
    {

        //prepare parameters, set events,...

    }

    APMReleaseContext();
}

Method APMIsConnected (C/C++)Permanent link for this heading

Call APMIsConnected to test, if the application has successfully registered to an app.telemetry agent.

Syntax

APMDECL_EXTERN int APMFUNC APMIsConnected();

Parameters:

This function does not take any arguments.

Return Value:

  • If the application is not connected to an app.telemetry agent this function returns zero.
  • If the function is successfully connected, the return value is one.

Usage Example

bool checkConnection()
{

    return (1 == APMIsConnected());

}

Method APMIsCompatible (C/C++)Permanent link for this heading

Call APMIsCompatible to test, if the application was linked with a version that is compatible with the dynamically loaded library.

Syntax

APMDECL_EXTERN int APMFUNC APMIsCompatible(UInt32 size, char *message);

Parameters:

  • size: Size in Bytes of the memory region where the second parameter points. Allocate at least 200 Bytes to get the full version message.
  • message: Pointer to a memory region of the size specified in the first parameter. A descriptive text with an optional product name and version number will be stored in the allocated memory region.

Return Value:

  • This function returns non-zero if the used versions are compatible.

Usage Example

bool checkCompatible()
{

  char version[300];

  return (FALSE != APMIsCompatible(300, version));

}

Explicit Transaction Functions (C/C++)Permanent link for this heading

The functions specified so far all are executed within the context of the current thread. In some cases it is necessary to explicitly define the current transaction context to the context handling functions, for example if your application's processes aren't based on operating system threads.

To use the explicit transaction functions, you have to define the symbolic constant APM_EXPLICIT_TRANSACTION in a preprocessor directive for your application. If only APM_EXPLICIT_TRANSACTION is defined, only the explicit transaction functions can be used. You have to define APM_THREAD_TRANSACTION in addition if you want to use the usual thread context functions from above.

Code Definition

#define APM_THREAD_TRANSACTION

#define APM_EXPLICIT_TRANSACTION

Method APMTxCreateContext (C/C++)Permanent link for this heading

Call APMTxCreateContext to create a new Software-Telemetry context analogously to APMCreateContext. You use the APMTransactionHandle returned by this function to pass to other explicit transaction functions for the definition of the current transaction context. You have to call APMTxReleaseContext with the returned transaction handle when exiting the context.

Syntax

APMDECL_EXTERN APMTransactionHandle APMFUNC APMTxCreateContext(APMTransactionHandle tx, APMApplicationHandle app, const char *filtervalue);

Parameters:

  • tx: Set this value to 0 in order to create a new transaction handle or use an already existing handle.
  • app: The Handle of the APMApplication representing this application.
  • filtervalue: (optional) This value is used to match a filter of a started Software-Telemetry session. You should register filter values used by calling APMRegisterFilterValue (see “Method APMRegisterFilterValue (C/C++)”)

Return Value:

This function returns the transaction handle for the current or currently created transaction context.

Usage Example

void beginRequestProcessing(/* ... */)
{

    
APMTransactionHandle tx = APMTxCreateContext(0,g_applicationHandle, "filter1");
    //...

    //proceed with application logic and fire events

    //...

    APMTxReleaseContext(tx);
}

Method APMTxAttachContext (C/C++)Permanent link for this heading

Call APMTxAttachContext to restore the context acquired through APMGetContext or APMTxGetContext in another thread or process (see “Passing Context” and “Method APMGetContext (C/C++)”). You can attach to an already existing transaction context or create a new transaction context which is returned by APMTxAttachContext to pass to other explicit transaction functions.

Syntax

APMDECL_EXTERN APMTransactionHandle APMFUNC APMTxAttachContext(APMTransactionHandle tx, APMApplicationHandle app, const APMContext *context);

Parameters:

  • tx: Set this value to 0 in order to create a new transaction handle or use an already existing handle.
  • app: The Handle of the APMApplication representing this application.
  • context: The context which you want to attach to.

Return Value:

This function returns the transaction handle for the current or currently created transaction context.

Usage Example

void ContinueRequest(/* ... */, const APMContext *context, APMSyncMark *syncMark)
{

    
APMTransactionHandle tx = APMTxAttachContext(0,g_applicationHandle, context);
    //...

    // continue with application logic and fire events

    //...

    APM
TxGetSyncMark(tx,syncMark);
    APM
TxReleaseContext(tx);
}

Method APMTxGetContext (C/C++)Permanent link for this heading

Call the APMTxGetContext-method to get a new context handle for the current transaction context, analogously to APMGetContext.

Syntax

APMDECL_EXTERN int APMFUNC APMTxGetContext(APMTransactionHandle tx, APMContext *context);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • context: APMGetContext creates a context at the location pointed to by context.

Return Value:

  • If the function succeeds, the return value is 1 and a context has been saved to the location which context pointed to.
  • If no context has been created, the return value is 0.

Usage Example

void initiateProcessing(/* ... */)
{

    
APMTransactionHandle tx = APMTxCreateContext(0,g_applicationHandle, "filterstring");
    APMContext context;

    APM
TxGetContext(tx,&context);

    //pass context to another thread, process on the same or a remote machine

    doRemote(/* data */, context);

    //do some local processing / wait for the remote processing to complete

    APMSyncMark syncMark;
    getRemoteResult(&syncMark);

    APM
TxSetSyncMark(tx,&syncMark);
    APM
TxReleaseContext(tx);
}

Method APMTxGetSyncMark (C/C++)Permanent link for this heading

Call the APMTxGetSyncMark-method to get a synchronization handle that can be passed to another thread/process/module to synchronize control flow, same as APMGetSyncMark, for the current transaction context.

Syntax

APMDECL_EXTERN int APMFUNC APMTxGetSyncMark(APMTransactionHandle tx, APMSyncMark *context);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • context: APMGetSyncMark creates a sync mark at the location pointed to by context.

Return Value:

  • If the function succeeds, the return value is 1 and a sync mark has been saved to the location which context pointed to.
  • If no sync-mark has been created, the return value is 0.

Usage Example

void doRemote(/* ... */, APMContext *context)
{

    
APMTransactionHandle tx = APMTxAttachContext(0,g_applicationHandle, context);

    //application logic, events, ...

    APMSyncMark syncMark;
    APM
TxGetSyncMark(tx,&syncMark);
    sendResultBack(/* ... */, syncMark);

    APM
TxReleaseContext(tx);
}

Method APMTxSetSyncMark (C/C++)Permanent link for this heading

Call APMTxSetSyncMark to pass a sync mark you got from APMGetSyncMark or APMTxGetSyncMark for synchronizing the sequence of events (see “Synchronizing Timeline with SyncMarks” and “Method APMGetSyncMark (C/C++)”).

Syntax

APMDECL_EXTERN void APMFUNC APMTxSetSyncMark(APMTransactionHandle tx, const APMSyncMark *context);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • context: The sync mark which you want to sync with.

Return Value:

This function does not return any value.

Usage Example

void initiateProcessing(/* ... */)
{

    
APMTransactionHandle tx = APMCreateContext(0,g_applicationHandle, "filterstring");
    APMContext context;

    APM
TxGetContext(tx,&context);

    //pass context to another thread, process or a remote server

    doRemote(/* data */, context);

    //do some local processing/wait for the remote processing to complete
    APMSyncMark syncMark;

    getRemoteResult(&syncMark);

    APM
TxSetSyncMark(tx,&syncMark);
    APM
TxReleaseContext(tx);
}

Method APMTxReleaseContext (C/C++)Permanent link for this heading

Call APMTxReleaseContext with the current transaction handle to finish logging and exit the context, analogously to APMReleaseContext.


Syntax

APMDECL_EXTERN void APMFUNC APMTxReleaseContext(APMTransactionHandle tx);

Parameters:

  • tx: The transaction handle of the current transaction context.

Return Value:

This function does not return any value.

Usage Example

void doRemote(/* ... */, APMContext *context)
{

  
APMTransactionHandle tx = APMTxAttachContext(0, g_applicationHandle, context);
  //application logic, events, ...

  APMSyncMark syncMark;

  APM
TxGetSyncMark(tx, &syncMark);
  sendResultBack(/* ... */, syncMark);

  APM
TxReleaseContext(tx);
}

Method APMTxHasActiveContext (C/C++)Permanent link for this heading

Call APMTxHasActiveContext to test if a software-telemetry session is active for some logging level for the current transaction context, analogously to APMHasActiveContext.

Syntax

APMDECL_EXTERN int APMFUNC APMTxHasActiveContext(APMTransactionHandle tx, APMEventLevel level);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • level: The event level of the event you prepare parameters for.

Return Value:

  • The return value is non-zero if the event will be logged.

Usage Example

void processRequest()
{

    
APMTransactionHandle tx = APMCreateContext(0,g_applicationHandle, "filter value");

    //application logic

    if (0 != APMTxHasActiveContext(tx,APM_EVENT_LEVEL_DEBUG))
    {

        //prepare parameters, set events,...

    }

    APM
TxReleaseContext(tx);
}

Method APMTxEvent (C/C++)Permanent link for this heading

Call the APMTxEvent function to log an event without parameters for the current transaction context.

Syntax

APMDECL_EXTERN void APMFUNC APMEvent(
    
APMTransactionHandle tx,
    APMModuleHandle module,

    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • The APMTxEvent function has the same 4 base parameters as APMEvent.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APM
TxEvent(tx, module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE);
    //...

Method APMTxEventArgs (C/C++)Permanent link for this heading

Use APMTxEventArgs to log an event for the current transaction context with various parameters, which must be passed in a predefined format.

Syntax

APMDECL_EXTERN void APMFUNC APMTxEventArgs(
    
APMTransactionHandle tx,
    APMModuleHandle module,

    APMEventId eventid,

    APMEventLevel level,

    APMEventFlags flags,

    UInt8 paramCount,

    APMParameterType *paramTypes,

    void *paramValues,

    unsigned paramValueSize);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • The APMTxEventArgs function has the 4 base parameters (see “Event Functions (C/C++)”).
  • paramCount: The number of parameters you want to pass to this function.
  • paramTypes: This is an array containing the types of the parameters. The size of the array is equal to paramCount.
  • paramValues: This pointer points to the continuous memory region containing the parameters.
  • paramValueSize: This is the size of the memory region containing the parameter values (paramValues).

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParameterType types[3] = {APM_PARAMETERTYPE_INT32,

        APM_PARAMETERTYPE_INT64, APM_PARAMETERTYPE_STRING};

    UInt32 par32 = 4;
    UInt64 par64 = 2147483698004;

    char parstr[] = "genericParam4";

    unsigned int size = (unsigned int)(sizeof(UInt32) + sizeof(UInt64) + sizeof(UInt16) + strlen(parstr));

    void *mem = calloc(1, size);
    if(mem) {

      char *bptr = (char *)(mem);

      *(UInt32 *)(bptr) = par32;

      bptr += sizeof(UInt32);

      *(UInt64 *)(bptr) = par64;

      bptr += sizeof(UInt64);

      *(UInt16 *)(bptr) = (UInt16)strlen(parstr);

      bptr += sizeof(UInt16);

      strncpy(bptr, parstr, strlen(parstr));

      APMTxEventArgs(tx, module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, 3, types, mem, size);
      free(mem);

    }

    //...

Method APMTxEventParam (C/C++)Permanent link for this heading

Call the APMTxEventParam-method to log events with a generic parameter structure analogously to APMEventParam for the current transaction context.

Syntax

APMDECL_EXTERN void APMFUNC APMTxEventParam(
    
APMTransactionHandle tx,
    
APMModuleHandle module,
    APMEventId eventid,

    APMEventLevel level,
    APMEventFlags flags,

    APMParamHandle param);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • The APMTxEventParam function has the 4 base parameters (see “Event Functions (C/C++)”).
  • param: This is the handle you obtained from a call to APMParamInit.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMParamHandle ph;

    ph = APMParamInit();

    APMParamAdd32(ph, 3);

    APMParamAdd64(ph, 2147483698003);

    APMParamAddString(ph, "genericParam3");

    APM
TxEventParam(tx, module, 123, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, ph);
    APMParamFree(ph);

    //...

Method APMTxEventStr (C/C++)Permanent link for this heading

Use APMTxEventStr to log an event with an additional string value as parameter.

Syntax

APMDECL_EXTERN void APMFUNC APMTxEventStr(
    
APMTransactionHandle tx,
  
  APMModuleHandle module,
  
  APMEventId eventid,
  
  APMEventLevel level,
  
  APMEventFlags flags,
  
  const char *param);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • The APMTxEventStr function has the 4 base parameters (see “Event Functions (C/C++)”).
  • param: Pointer to null-terminated, utf8-encoded string. The maximum string length allowed is 32768 Byte.

Return Value:

This function does not return any value.

Usage Example

    //steps required before logging events:
    // * application registered,

    // * module is a handle to a registered module,

    // * id is the id of a registered event,

    // * a context has been created or attached

    APMEventStr(module, id, APM_EVENT_LEVEL_DEBUG, APM_FLAG_NONE, "stringparam1");

    //...

Method APMTxReport (C/C++)Permanent link for this heading

Call APMTxReport to create a new feedback report, see "Method APMReport (C/C++)".

Syntax

APMDECL_EXTERN void APMFUNC APMTxReport(
    
APMTransactionHandle tx,
    APMApplicationHandle app,

    const char *filtervalue,

    const char *reportkey,

    const char *description);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • app: The Handle of the APMApplication representing this application.
  • filtervalue: filtervalue to match requests with.
  • reportkey: A key value may be generated by the calling application to associate further descriptions to a feedback. If empty, a new feedback report will be generated on each call and no further information may be attached to the feedback.
  • description: Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32768 Bytes.

Return Value:

This function does not return any value.

Usage Example

    //application logic, context created / attached
    APM
TxReport(tx, g_applicationHandle, "filter1", null, "Description entered by the user / application generated description");

Method APMTxReportValue (C/C++)Permanent link for this heading

Call APMTxReportValue to add a key/value pair to an existing report.

Syntax

APMDECL_EXTERN void APMFUNC APMTxReportValue(
    
APMTransactionHandle tx,
    APMApplicationHandle app,

    const char *reportkey,
    const char *key,

    const char *value);

Parameters:

  • tx: The transaction handle of the current transaction context.
  • app: The Handle of the APMApplication representing this application.
  • reportkey: reportkey matches the reportkey of the APMReport function to associate the value with the report session.
  • key: A key describes the meaning of the value. Only one value can be associated to a single key in one report session.
  • value: Text (max. 32 kBytes).

Return Value:

This function does not return any value.

Usage Example

    //application logic, context created / attached
    APM
TxReport(tx, g_applicationHandle, "filter1", "abc", "Description entered by the user / application generated description");
    APM
TxReportValue(tx, g_applicationHandle, "abc", "firstname", "John");
    APM
TxReportValue(tx, g_applicationHandle, "abc", "lastname", "Doe");