.NET API Reference

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

Since version 2023 the Software-Telemetry API supports .NET 6 whereas .NET Framework is no longer supported.

Configure Visual Studio .NET Project

In order to use the Software-Telemetry API in your Microsoft Visual Studio .NET project you have to include app.telemetry API .NET library softwaretelemetry.dll which comes with the app.telemetry API developer resources.

Follow the described steps to include the required resources.

In the Solution Explorer you have to open the context-menu on the project which should be analyzed and click “Properties”. Choose the tab “Reference Paths”. Browse to the Folder where “softwaretelemetry.dll” is located (which is delivered with the app.telemetry Software-Telemetry SDK resources) and add this folder to the Reference paths list.

You also have to add the softwaretelemetry.dll library to the project references.

Select the References-folder in the Solution Explorer of your project and open the context menu and click “Add Reference ...“. Select the softwaretelemetry.dll library via the "Browse" tab from the same location as configured above.

After the references to the softwaretelemetry.dll library is configured correctly you can use the library like this:

using apm;

Here you can see an overview of the app.telemetry Software-Telemetry SDK APM classes inside Microsoft Visual Studio:

The .NET Software-Telemetry SDK is defined in the namespace “apm” which has to be imported by the statement “using apm;” in order to use any constants or methods from the classes defined in the SDK.

NuGet Package

Since version 2023 the .NET Software-Telemetry SDK is published additionally as "softwaretelemetry" NuGet Package.

Constants (.NET)

All the constants are static members of the APM class and can be accessed in a static way.

Flags (.NET)

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 on the base class APM with the data type Byte and have the following possible values:

• FLAG_NONE
• FLAG_ENTER
• FLAG_LEAVE
• FLAG_WAIT
• FLAG_WARNING
• FLAG_ERROR
• FLAG_PROCESS_INFO

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

Log Level (.NET)

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 on the base class APM with the data type Byte and have the following possible values:

• EVENT_LEVEL_LOG
• EVENT_LEVEL_IPC (only internal)
• EVENT_LEVEL_NORMAL
• EVENT_LEVEL_DETAIL
• EVENT_LEVEL_DEBUG

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

Predefined Modules (.NET)

To use a predefined module create a new APMModule object (by means of calling the constructor) with the predefined module name. This object will be used later to fire events for that module.

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

Predefined Events (.NET)

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

All predefined events are declared and available as global constants on the base class “APM”.

Error/Trace Events:

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

• EVENT_ERROR
• EVENT_WARNING
• EVENT_INFO
• EVENT_TRACE

Predefined Application Property Keys and Names (.NET)

View the language agnostic Application Properties section for an explanation of the properties listed below.

All predefined application property keys and names are available as public constants on the APM class.

• PROPERTY_INSTANCE_GUID_KEY with name PROPERTY_INSTANCE_GUID_NAME

Predefined Application Value Keys and Names (.NET)

View the language agnostic Application Values section for an explanation of the properties listed below.

All predefined application value keys and names are available as public constants on the APM class.

• VALUE_VERSION_KEY with name VALUE_VERSION_NAME
• VALUE_INSTANCE_NAME_KEY with name VALUE_INSTANCE_NAME_NAME

Aggregation Function Names (.NET)

The Aggregation Function Names are static members of the APMCounterOptions class and can be accessed in a static way.

Data Types / Class Overview (.NET)

APM (.NET)

The APM class is the base class of the Software-Telemetry SDK. It contains all global defined constants as described in chapter „Constants (.NET)”. Use the methods from the APM class in a static way (there is no new instance allocation required).

The APM class supports the following global static methods which do not require an application scope or status:

• Connect
• Disconnect
• IsConnected
• IsCompatible
• DetachThread
• AttachThread
• RegisterCounter
• UpdateCounter
• UnregisterCounter

A detailed description of this class with all methods explained is described in chapter “APM Class and Methods (.NET)”.

APMApplication (.NET)

APMApplication is the base class for own application implementation and handles the request scope and reporting functions.

After creating an instance with the class constructor passing the application registration information, it stores the application handle inside and provides all context-specific functions for your application.

The APMApplication class supports the following instance/class methods which require an application scope and have to be called on your object instance of APMApplication:

• RegisterFilterValue
• RegisterApplicationProperty
• RegisterApplicationValue
• CreateContext
• AttachContext
• ReleaseContext
• GetContext
• GetSyncMark
• SetSyncMark
• HasActiveContext
• Report
• ReportValue
• ReportContent
• ReportFile

A detailed description of this class with all methods explained is described in chapter “APMApplication Class and Methods (.NET)”.

APMModule (.NET)

APMModule is the base class for own module implementation and is used to fire instrumentation events.

After creating an instance with the class constructor passing the module name, it stores the module handle inside and provides all module-specific functions for your application.

The APMModule class supports the following instance/class methods which require a module scope and have to be called on your object instance of APMModule:

• RegisterEvent
• Event
• EventStr
• EventParam

A detailed description of this class with all methods explained is described in chapter “APMModule Class and Methods (.NET)”.

APMParameter (.NET)

APMParameter is used as data class for generic event parameters.

To define any parameters used in events you have to create a new APMParameter instance and add the typed parameters to that instance:

• AddInt32
• AddInt64
• AddString

A detailed description of this class with all methods explained is described in chapter “APMParameter Class and Methods (.NET)”.

APMCounterType (.NET)

The enum APMCounterType specifies the type of counter registered using the method RegisterCounter of the APM class.

ComputeCounter Delegates (.NET)

The counter value is provided to the app.telemetry library as return value of one of the following delegates:

These delegates are used as parameters in the method RegisterCounter of the APM class.

APMCounterOptions (.NET)

The APMCounterOptions class contains counter attributes as fields. 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 in the method RegisterCounter of the APM class.

APMUpdateCounterOptions (.NET)

The APMUpdateCounterOptions class is similar to the APMCounterOptions class, but it contains only the counter attributes that may be updated for a registered counter.

APM Class and Methods (.NET)

The APM class is the base class of the Software-Telemetry SDK. It contains all global defined constants as described in chapter „Constants (.NET)”. Use the methods from the APM class in a static way (there is no new instance allocation required).

Remarks:

With version 2010 Fall Release the application-specific functions (CreateContext, ..., Report, ...) of the .Net API where moved to the APMApplication class (see chapter “APMApplication Class and Methods (.NET)”) and have to be called on an object instance of this class!

The Methods Connect/Disconnect and all counter functionality (RegisterCounter/UpdateCounter/UnregisterCounter) is available since version 2023.

Method Connect (.NET)

Call Connect to establish a connection to the app.telemetry agent.

Parameters:

This function does not take any arguments.

Return Value:

This function does not return any value.

Method Disconnect (.NET)

Call Disconnect to disconnect from the app.telemetry agent, this will also cleanup the app.telemetry communication thread and will disable automatic reconnection. To reestablish the connection to the app.telemetry agent call Connect.

Parameters:

This function does not take any arguments.

Return Value:

This function does not return any value.

Method IsConnected (.NET)

The API method IsConnected will tell you if the application (the one that is instrumented with the APM SDK) has successfully registered to an app.telemetry agent and is currently connected to the agent process.

Only when an application is successfully connected to an app.telemetry agent, Software-Telemetry data will be processed and sent to and collected by the app.telemetry server

Parameters:

This function does not take any arguments.

Return Value:

• true: if the application has successfully registered to and connected to an app.telemetry agent.
• false: if the application has not registered or is currently not connected to an app.telemetry agent or if the native Software-Telemetry library is not loaded correctly.

Method IsCompatible (.NET)

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

Parameters:

• message (String): An output parameter containing the result of the IsCompatible check.

Return Value:

• true: if the used versions are compatible
• false will be returned otherwise (versions not compatible) – the message object will contain details about the incompatibility

Method DetachThread (.NET)

Call the DetachThread-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 AttachThread-method to resume processing (see “Method AttachThread (.NET)”).

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.

Parameters:

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

Return Value:

• If the function succeeds, the return value is true and the transaction handle has been filled.
• The function will return false in case the library is not available or if no request has been started using CreateContext and/or AttachContext.

Remarks:

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

Method AttachThread (.NET)

Call the AttachThread-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 DetachThread-method to restore the recorded state of the request.

For more details see “Method DetachThread (.NET)”.

Parameters:

• transaction: AttachThread uses the transaction handle generated by DetachThread to identify the current state of the request.

Return Value:

This function does not return any value.

Method RegisterCounter (.NET)

Call RegisterCounter once for every counter or counter instance to make the counter known to the app.telemetry library for collection. There exist three overloaded methods of RegisterCounter corresponding to the three possible data types for counter, UInt32, UInt64 and String.

Parameters:

• group: The group name of the counter. Note: Group names starting with “apm” are reserved for internal use and must not be used by application developers.
• name: The name of the counter.
• type: The counter type, see "APMCounterType (.NET)".
• fn: The ComputeCounter delegate, see "ComputeCounter Delegates (.NET)".
• options: Instance of the APMCounterOptions class that defines additional counter attributes, see "APMCounterOptions (.NET)".
• Return Value:
• This function returns the handle to the counter that can be used to change some attributes and to unregister the counter again.

Method UpdateCounter (.NET)

Call UpdateCounter to update some of the attributes of a registered counter. The attributes that can be updated are defined as fields of the APMUpdateCounterOptions (see "APMUpdateCounterOptions (.NET)") class:

• GroupDisplayName
• DisplayName
• InstanceDisplayName

Parameters:

• counterHandle: The handle of the registered counter whose attributes need to be updated, returned by RegisterCounter
• options: Instance of the APMUpdateCounterOptions class that defines the counter attributes to be updated.

Return Value:

This function does not return any value.

Method UnregisterCounter (.NET)

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

Parameters:

• counterHandle: The handle of the registered counter that will be unregistered.
• Return Value:

This function does not return any value.

APMApplication Class and Methods (.NET)

The APMApplication class is the base class for your application registration, the context- and report-functions and the filter registration (callback or directly). It stores the application handle inside and provides all application-specific functions for your application to be called on your APMApplication object instance.

Your own application implementation may override the callback function EnumFilterValuesCallback (default implementation is empty) to provide the filters values via the callback function. Alternatively the filters may also be registered directly.

The application is registered when a new instance of the APMApplication class is being created.

Constructor APMApplication (.NET)

Parameters:

• appName: The name of your application
• appId: The id of your application
• appTier: The tier inside the application
• appTierId: id to distinguish multiple services of one application tier

Property ApplicationHandle (.NET)

ApplicationHandle lets you obtain the corresponding UInt32 handle of the application, it is read-only.

Method RegisterApplicationProperty (.NET)

Call RegisterApplicationProperty to register additional application registration properties immediately after you call to the APMApplication class constructor to ensure proper operation.

Parameters:

• propertyKey: The application defined key of the property or the predefined PROPERTY_INSTANCE_GUID_KEY. Limited to 256 utf-8 encoded Bytes. Keys starting with “apm:” are reserved for internal use.
• propertyName: The display name of the property (PROPERTY_INSTANCE_GUID_NAME for the example above). Limited to 512 utf-8 encoded Bytes.
• propertyValue: The value of the property. Limited to 32768 utf-8 encoded Bytes.

Remarks:

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

Method RegisterApplicationValue (.NET)

Parameters:

• valueKey: The application defined key of the value or one of the predefined (VALUE_VERSION_KEY, VALUE_INSTANCE_NAME_KEY, ...). Limited to 256 utf-8 encoded Bytes. Keys starting with “apm:” are reserved for internal use.
• valueName: The display name of the property (VALUE_VERSION_NAME, VALUE_INSTANCE_NAME_NAME,... for the examples above). Limited to 512 utf-8 encoded Bytes.
• value: The value of the property. Limited to 32768 utf-8 encoded Bytes.

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.

Method Unregister (.NET)

The method Unregister will unregister the application and will tell the app.telemetry Library to disconnect from the app.telemetry agent. It is not valid to call further methods on that object after unregistering.

Method RegisterFilterValue (.NET)

RegisterFilterValue registers application specific filter item, which may be used as filter strings in the CreateContext function. Registering the filter values helps the user selecting filters when starting Software-Telemetry sessions in the client interface.

To improve the registration process enumerating the possible filter values, instead of registering the filter values by calling RegisterFilterValues right after application registration, you may create a subclass of APMApplication implementing the callback function EnumAppFilterValuesCallback. This callback method will be invoked only if no application with same application name, application id and application tier has already registered filter values. Enumerate and register the filter values in the callback function. This mechanism is designed e.g. for web service farms, where the enumeration of the filters will register all users. So it is sufficient to register the filter values once on one web service instance.

Parameters:

• filterValue (String): The exact filter value as a string as used in the CreateContext method. (e.g. the user login string: "domain\user.name")
• filterDescription (String): Description string of the filter. (e.g. a display string for the user login: "full user name")

Return Value:

This function does not return any value.

Remarks:

You should register all filters that are available in your application so that the user can choose in the client interface from a list box.

Method CreateContext (.NET)

Call CreateContext to start a new request in the Software-Telemetry context.

If the filter value matches a currently started session filter, logging is started for the current execution thread and the request will be associated with the session. You may call CreateContext more than once in one request in order to pass additional filter values. The request will start at the first CreateContext and will be finished by the first ReleaseContext. Make sure to call ReleaseContext (see “Method ReleaseContext (.NET)”) when exiting the request.

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.

Parameters:

• filtervalue (String): (may be empty) Value to be matched against the session start value.

Return Value:

This function does not return any value.

See chapter “Application Properties” for more information on the app.telemetry request concept.

Method ReleaseContext (.NET)

Call ReleaseContext to indicate the end of the processing of one request. One ReleaseContext will close the request no matter how many CreateContext or AttachContext calls have been called.

Remarks:

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

Method GetContext (.NET)

Call the GetContext-method to get a new context handle from the SDK.

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 other thread/process/module which has to call the AttachContext-method with the same context.

For more information see also “Passing Context” and “Method AttachContext (.NET)”.

Parameters:

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

Return Value:

• true: if the function succeeds, the return value is true and a context has been saved to the out parameter requestinfo.
• false: if no context has been created.

Method AttachContext (.NET)

Call AttachContext to restore the context acquired through GetContext in another thread or process.

For more information see also “Passing Context” and “Method GetContext (.NET)”.

Parameters:

• requestinfo: The context which you want to attach to. You get such a context by calling GetContext.

Method GetSyncMark (.NET)

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

The difference between a sync-marks 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/modules belonging to the same request.
• A sync-mark is only a time synchronization handle between the different threads/processes/modules which can be used several times to synchronize the control flow exactly (different systems may have different timestamps and different time precision).

For more information see also “Synchronizing Timeline with SyncMarks”.

Parameters:

• syncMark: GetSyncMark creates a sync-mark at the location pointed to by syncMark.

Return Value:

• true: if the function succeeds, the return value is true and a sync-mark has been saved to the out parameter syncMark.
• false: if no sync-mark has been created.

Method SetSyncMark (.NET)

Call the SetSyncMark-method to pass and submit a synchronization handle that you got from the GetSyncMark-call to synchronize the sequence of events.

For more information see also “Synchronizing Timeline with SyncMarks”, “Method GetSyncMark (.NET)” and “Method GetContext (.NET)”.

Parameters:

• syncMark: The sync-mark which you want to sync with.

Return Value:

This function does not return any value.

Method HasActiveContext (.NET)

The API method HasActiveContext defined in the APMApplication class will tell you if there is currently a Software-Telemetry session for the given log level for the application (the one that is instrumented with the APM SDK) running.

This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Parameters:

• Level (Byte): Software-Telemetry log level to be checked.

Return Value:

• true: if logging is active for this application for the given log level.
• false: otherwise (if logging is not active for the given log level) or if the native Software-Telemetry library is not loaded correctly.

Method Report (.NET)

Call the Report-method from the APMApplication class 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.

Parameters:

• filtervalue (String): the raw filter value, which was registered with RegisterFilterValue
• reportkey (String): 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.
• description (String): Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32 768 Bytes.

Return Value:

This function does not return any value.

Method ReportValue (.NET)

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

For more information see “Method Report (.NET)”.

Parameters:

• reportkey (String): match the reportkey of the Report function to associate the value with the report session.
• key (String): A key describes the meaning of the value. Only one value can be associated to a key in one report session.
• Value (String): Textual value (max. 32 kBytes).

Return Value:

This function does not return any value.

Method ReportContent (.NET)

Call ReportContent to add content to an existing report.

For more information see “Method Report (.NET)”.

Parameters:

• reportkey (String): match the reportkey of the Report function to associate the content with the report session.
• filename (String): A filename describing the content of the file. (max. 256 Bytes) – this is the name of the file in the reported session with which the data is persisted.
• mimetype (String): MIME-Type of content – (e.g.: text/plain, image/png, ...) – later used for presentation of content.
• data (byte[]): Byte array containing binary data.

Return Value:

This function does not return any value.

Method ReportFile (.NET)

Call ReportFile to add content to an existing report.

For more information see “Method Report (.NET)”.

Parameters:

• reportkey (String): match the reportkey of the Report function to associate the content with the report session.
• filename (String): A filename describing the content of the file. (max. 256 Bytes) – this is the name of the file in the reported session with which the data is persisted.
• mimetype (String): MIME-Type of content – (e.g.: text/plain, image/png, ...) – later used for presentation of content.
• stream (System.IO.Stream): Stream to read the content from. The content will be read in junks of 4 kBytes and transferred to the server.

Return Value:

This function does not return any value.

APMModule Class and Methods (.NET)

The APMModule-class represents a registered Module. You have to register a module to set telemetry points. You may register a module multiple times with the same name. Events of equally named modules will show up in the same column.

Constructor APMModule (.NET)

The constructor registers the module with the given name.

Method RegisterEvent (.NET)

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 RegisterEvent-method will tell the app.telemetry server a name for every event-ID and optionally parameter descriptions for the parameters used in the event calls.

Parameters:

• eventid (UInt64): Unique ID of event which is used later on for every instrumentation point.
• eventDescription (String): Description string of event. A describing name for that event.
• parameterDescription (String): 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.

Method Event (.NET)

Call the simple Event-method to log events 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.

This method is part of the APMModule class and has to be called on your own module implementation class.

Parameters:

• eventid (UInt64): id of the event being processed. Should be defined as constant in your module implementation class.
• level (Byte): event detail level for filtering. For the list of available log levels see chapter “Log Level (.NET)”.
• flags (Byte): flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a logic OR (|). For the list of available flags see chapter “Predefined Events (.NET)”.

Return Value:

This function does not return any value.

Method EventStr (.NET)

Call the EventStr-method to log events with a single textual (string) parameter.

In addition to the event-ID (with the registered event name) and the flags a single string parameter value will be logged.

For more information see “Method Event (.NET)”.

Parameters:

• eventid (UInt64): id of the event being processed. Should be defined as constant in your module implementation class.
• level (Byte): event detail level for filtering. For the list of available log levels see chapter “Log Level (.NET)”.
• flags (Byte): flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a logic OR (|). For the list of available flags see chapter “Predefined Events (.NET)”.
• param (String): a string parameter to be logged – can be any textual or preformatted message.

Return Value:

This function does not return any value.

Method EventParam (.NET)

Call the EventParam-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 EventParam-method you have to allocate a new APMParameter. With a few helper methods you can add values to this parameter object and finally you can use the parameter object in the event function to be logged. For details how to allocate and fill the APMParameter object see chapter “APMParameter Class and Methods (.NET)”.

Parameters:

• eventid (UInt64): id of the event being processed. Should be defined as constant in your module implementation class.
• level (Byte): event detail level for filtering. For the list of available log levels see chapter “Log Level (.NET)”.
• flags (Byte): flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a logic OR (|). For the list of available flags see chapter “Predefined Events (.NET)”.
• param (APMParameter): the parameter object containing any number of values to be logged.

Return Value:

This function does not return any value.

APMParameter Class and Methods (.NET)

The APMParameter-class is an object structure for storing and managing parameter values that can be used for logging complex value structures with more than one or different type of values.

See also “Method EventParam (.NET)”.

Constructor APMParameter (.NET)

Call the APMParameter-constructor to allocate a new parameter object where you can add any number of textual (string) values and integer values (32- and 64-bit).

Method AddInt32 (.NET)

Call the method AddInt32 on your APMParameter-instance to add a simple integer value (32-bit) to that object.

Parameters:

• value (UInt32): 32-bit integer value to be added to the parameter object.

Return Value:

This function does not return any value.

Method AddInt64 (.NET)

Call the method AddInt64 on your APMParameter-instance to add a simple integer value (64-bit) to that object.

Parameters:

• value (UInt64): 64-bit integer value to be added to the parameter object.

Return Value:

This function does not return any value.

Method AddString (.NET)

Call the method AddString on your APMParameter-instance to add a textual (string) value to that object.

Parameters:

• value (String): textual parameter value to be added to the parameter object.

Return Value:

This function does not return any value.