.NET API Reference
2018 Update Rollup 2

.NET API ReferencePermanent link for this heading

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.

Configure Visual Studio .NET ProjectPermanent link for this heading

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

Constants (.NET)Permanent link for this heading

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

Flags (.NET)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 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)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 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)Permanent link for this heading

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

Usage Example

APMModule mod1 = new APMModule(APM.MODULE_NAME_OS);

APMModule mod2 = new APMModule(APM.MODULE_NAME_XMLHTTP);

Predefined Events (.NET)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”.

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

Data Types / Class Overview (.NET)Permanent link for this heading

APM (.NET)Permanent link for this heading

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:

  • IsConnected
  • IsCompatible
  • DetachThread
  • AttachThread

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

APMApplication (.NET)Permanent link for this heading

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
  • 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)Permanent link for this heading

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)Permanent link for this heading

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

APM Class and Methods (.NET)Permanent link for this heading

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!

Method IsConnected (.NET)Permanent link for this heading

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

Syntax

public static Boolean IsConnected();

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.

Usage Example

private void isConnected_Click(object sender, EventArgs e)

{

    isConnectedResult.Text = (APM.IsConnected()) ? "yes" : "no";

}

Method IsCompatible (.NET)Permanent link for this heading

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

Syntax

public static Boolean IsCompatible(ref String message);

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

Usage Example

String message = "";

if (!APM.IsCompatible(ref message)) {

    //incompatible
    Console.WriteLine(message);

}

Method DetachThread (.NET)Permanent link for this heading

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.

Syntax

public static Boolean DetachThread(out UInt64 transaction)

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.

Usage Example

public class Task {

    //...
    public UInt64 tx;

    //...

    public void Initialize(/* ... */)
    {

        app.CreateContext("filterstring");
        module.Event(EVENT_ENTER_TASK_TO_QUEUE, APM.EVENT_LEVEL_NORMAL, APM.FLAG_ENTER);

        APM.DetachThread(out tx);

        schedule();

    }

    public void process()
    {

        APM.AttachThread(tx);
        module.Event(EVENT_REMOVE_TASK_FROM_QUEUE, APM.EVENT_LEVEL_NORMAL, APM.FLAG_LEAVE);

        // process work

        app.ReleaseContext();
    }

}

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)Permanent link for this heading

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

Syntax

public static void AttachThread(UInt64 transaction);

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.

Usage Example

See Method DetachThread (.NET)

APMApplication Class and Methods (.NET)Permanent link for this heading

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)Permanent link for this heading

Syntax

public APMApplication(string appName, string appId,
                      string appTier, string appTierId);

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

Method Unregister (.NET)Permanent link for this heading

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.

Syntax

public void Unregister();

Method RegisterFilterValue (.NET)Permanent link for this heading

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.

Syntax

public void RegisterFilterValue(String filterValue,
                                String filterDescription);

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.

Usage Example

class TestApplication : APMApplication {

    public TestApplication (String appTierId)
    
       : base("Fabasoft app.telemetry", "Demo", "App1", appTierId)
  
  {

        // ...
  
  }

    public override void EnumAppFilterValuesCallback()
  
  {

        RegisterFilterValue("user1", "displayname1");
    
    RegisterFilterValue("user2", "displayname2");
    
    RegisterFilterValue("user3", "displayname3");
    
    RegisterFilterValue("user4", "displayname4");
    
    RegisterFilterValue("user5", "displayname5");

    }
}

Method CreateContext (.NET)Permanent link for this heading

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.

Syntax

public void CreateContext(String filtervalue);

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 “Request and Context Handling” for more information on the app.telemetry request concept.

Usage Example

public static void doRequest(APMApplication app, string sequenceId)
{

  
  app.CreateContext(FILTER_VALUE);

    /* place you request processing code here ... */

    app.ReleaseContext();
}

Method ReleaseContext (.NET)Permanent link for this heading

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.

Syntax

public void ReleaseContext();

Remarks:

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

Usage Example

public static void doRequest(APMApplication app, string sequenceId)
{

  
  app.CreateContext(FILTER_VALUE);

    /* place you request processing code here ... */

    app.ReleaseContext();
}

Method GetContext (.NET)Permanent link for this heading

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

Syntax

public Boolean GetContext(out byte[] requestinfo);

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.

Usage Example

public void GetRepositoryInfo()
{

    // ...

    byte[] context;
    app.GetContext(out context);

    request.Headers.Add("x-apm-telemetry-context",
            System.Convert.ToBase64String(context));

    // ...

    HttpWebResponse response = (HttpWebResponse)request.GetResponse();
    String syncMark = response.GetResponseHeader("x-apm-telemetry-syncmark");

    if (syncMark != null) {
        app.SetSyncMark(Convert.FromBase64String(syncMark));
    }

    // ...
}

Method AttachContext (.NET)Permanent link for this heading

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

Syntax

public void AttachContext(byte[] requestinfo);

Parameters:

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

Usage Example

void ContinueRequest(byte[] requestinfo) {
    m_application.AttachContext(requestinfo);

}

Method GetSyncMark (.NET)Permanent link for this heading

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

Syntax

public Boolean GetSyncMark(out byte[] syncMark);

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.

Usage Example

void continueRequest(APMApplication appl)
{

    byte []syncMark;

    Boolean success = app.GetSyncMark(syncMark);

}

Method SetSyncMark (.NET)Permanent link for this heading

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

Syntax

public void SetSyncMark(byte[] syncMark);

Parameters:

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

Return Value:

This function does not return any value.

Usage Example

See Method GetContext (.NET)”.

Method HasActiveContext (.NET)Permanent link for this heading

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.

Syntax

public Boolean HasActiveContext(Byte level);

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.

Usage Example

private void hasContext_Click(object sender, EventArgs e) {
    Byte level = getEventLevel(hasContextLevel.SelectedIndex);

    hasCtxResult.Text = (app.HasActiveContext(level)) ? "yes" : "no";

}

Method Report (.NET)Permanent link for this heading

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.

Syntax

public void Report(String filtervalue, String keyvalue, String description);

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.

Usage Example

public APMApplication app;

public void RegisterTelemetry {
    app = new APMApplication("appName", "appId", "appTier
Name", "appTierId");
}

public void generateReport(String username, String description) {
    app.Report(username, "repkey_1", description);

    app.ReportValue("repkey_1", "username", "John Doe");

    System.Text.UTF8Encoding enc = new System.Text.UTF8Encoding();
    byte[] var = enc.GetBytes("any text");

    app .ReportContent("repkey_1", "my-text.txt",
"text/plain", ref var);

    Stream stream = File.OpenRead(reportFilePath);
    app.ReportFile("repkey_1", "my-image.png", "image/png", stream);

}

Method ReportValue (.NET)Permanent link for this heading

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

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

Syntax

public void ReportValue(string reportkey, string key, string value);

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.

Usage Example

See Method Report (.NET)

Method ReportContent (.NET)Permanent link for this heading

Call ReportContent to add content to an existing report.

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

Syntax

public void ReportContent(string reportkey, string filename, string mimetype, ref byte[] data);

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.

Usage Example

See Method Report (.NET)

Method ReportFile (.NET)Permanent link for this heading

Call ReportFile to add content to an existing report.

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

Syntax

public void ReportFile(string reportkey, string filename, string mimetype, System.IO.Stream stream);

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.

Usage Example

See Method Report (.NET)

APMModule Class and Methods (.NET)Permanent link for this heading

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)Permanent link for this heading

The constructor registers the module with the given name.

Syntax

public APMModule(string name);

Method RegisterEvent (.NET)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 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.

Syntax

public void RegisterEvent(UInt64 eventid, String eventDescription, String parameterDescription);

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.

Usage Example

public void ModuleEvents()
{

  module = new APMModule("mymodule");

  module.RegisterEvent(101, "eventdesc1", "name;count;size");

  module.RegisterEvent(102, "eventdesc2", null);

  module.RegisterEvent(103, "eventdesc3", null);

  module.RegisterEvent(104, "eventdesc4", null);

  module.RegisterEvent(105, "eventdesc5", null);

}

Method Event (.NET)Permanent link for this heading

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.

Syntax

public void Event(UInt64 eventid, Byte level, Bytes flags);

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.

Usage Example

public void WebShopWebMethod(object sender, EventArgs e) {
    // ...

    m_module.Event(SampleModule.EVENT_PROCESS_REQUEST,
        APM.EVENT_LEVEL_NORMAL, APM.FLAG_ENTER);

    GetRepositoryInfo();
    GetStockServiceInfo();

    m_module.Event(SampleModule.EVENT_PROCESS_REQUEST,
        APM.EVENT_LEVEL_NORMAL, APM.FLAG_LEAVE);

    // ...
}

Method EventStr (.NET)Permanent link for this heading

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

Syntax

public void EventStr(UInt64 eventid, Byte level, Bytes flags, String param);

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.

Usage Example

public void WebShopWebMethod(object sender, EventArgs e) {
    // ...

    m_module.EventStr(SampleModule.EVENT_PROCESS_REQUEST,
        APM.EVENT_LEVEL_NORMAL, APM.FLAG_ENTER, “enter web-method”);

    GetRepositoryInfo();
    GetStockServiceInfo();

    m_module.EventStr(SampleModule.EVENT_PROCESS_REQUEST,
        APM.EVENT_LEVEL_NORMAL, APM.FLAG_LEAVE, “leave web-method”);

    // ...
}

Method EventParam (.NET)Permanent link for this heading

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

Syntax

public void EventParam(UInt64 eventid, Byte level, Byte flags, APMParameter param);

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.

Usage Example

public void WebShopWebMethod(object sender, EventArgs e) {
    // ...

    APMParameter param = new APMParameter();

    param.AddInt32(75);
    param.AddInt64(2147483698002);

    param.AddString("enter WebShop web-method");

    module.EventParam(SampleModule.EVENT_PROCESS_REQUEST,
        APM.EVENT_LEVEL_NORMAL, APM.FLAG_ENTER, param);

    // ...
}

APMParameter Class and Methods (.NET)Permanent link for this heading

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)Permanent link for this heading

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

Syntax

public APMParameter();

Method AddInt32 (.NET)Permanent link for this heading

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

Syntax

public void AddInt32(UInt32 value);

Parameters:

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

Return Value:

This function does not return any value.

Usage Example

See Method EventParam (.NET)”.

Method AddInt64 (.NET)Permanent link for this heading

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

Syntax

public void AddInt64(UInt64 value);

Parameters:

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

Return Value:

This function does not return any value.

Usage Example

See Method EventParam (.NET)”.

Method AddString (.NET)Permanent link for this heading

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

Syntax

public void AddString(String value);

Parameters:

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

Return Value:

This function does not return any value.

Usage Example

See Method EventParam (.NET)”.