ADEumInstrumentation Class Reference

Inherits from NSObject
Declared in ADEumInstrumentation_interfaces.h

Overview

AppDynamics iOS SDK

Initialization

+ initWithKey:

Initializes the SDK.

+ (void)initWithKey:(NSString *)appKey

Parameters

appKey

The application key.

Discussion

This method should be called once, early in your application’s startup sequence.

Warning: appKey must not be nil.

Declared In

ADEumInstrumentation_interfaces.h

+ initWithKey:collectorUrl:

Initializes the SDK.

+ (void)initWithKey:(NSString *)appKey collectorUrl:(NSString *)collectorUrl

Parameters

appKey

The application key.

collectorUrl

The URL of the collector. The SDK will send beacons to this collector.

Discussion

This method should be called once, early in your application’s startup sequence.

Warning: appKey must not be nil.

Warning: collectorUrl must not be nil. Otherwise, an NSInvalidArgumentException will be thrown.

Declared In

ADEumInstrumentation_interfaces.h

+ initWithConfiguration:

Initializes the SDK.

+ (void)initWithConfiguration:(ADEumAgentConfiguration *)agentConfiguration

Parameters

agentConfiguration

The configuration to use.

Discussion

This method should be called once, early in your application’s startup sequence.

Warning: agentConfiguration must not be nil. Otherwise, an NSException will be thrown.

Declared In

ADEumInstrumentation_interfaces.h

+ changeAppKey:

Changes the application key.

+ (void)changeAppKey:(NSString *)appKey

Parameters

appKey

The new application’s key.

Discussion

The SDK doesn’t send all instrumentation data immediately, and calling this method causes all unsent data to be discarded. Use this method sparingly.

Warning: appKey must not be nil. Otherwise, an NSException will be thrown.

Declared In

ADEumInstrumentation_interfaces.h

Instrumenting application methods

+ beginCall:selector:withArguments:

Call this method at the beginning of a method’s execution to track that method invocation.

+ (id ADEUM_NULLABLE)beginCall:(id)receiver selector:(SEL)selector withArguments:(NSArray *ADEUM_NULLABLE)arguments

Parameters

receiver

The object to which this message was sent.

selector

The selector describing the message that was sent.

arguments

The values of the arguments of this method call. This parameter is optional and may be nil. Additionally, you are free to send only a subset of the actual arguments.

Return Value

An object that must be passed to endCall:.

Discussion

Warning: receiver must not be nil.

Warning: selector must not be nil.

Declared In

ADEumInstrumentation_interfaces.h

+ beginCall:selector:

Call this method at the beginning of a method’s execution to track that method invocation.

+ (id ADEUM_NULLABLE)beginCall:(id)receiver selector:(SEL)selector

Parameters

receiver

The object to which this message was sent.

selector

The selector describing the message that was sent.

Return Value

An object that must be passed to endCall:.

Discussion

Equivalent to beginCall:receiver selector:selector arguments:nil.

Declared In

ADEumInstrumentation_interfaces.h

+ beginCall:methodName:withArguments:

Call this method at the beginning of a method’s execution to track that method invocation.

+ (id)beginCall:(NSString *)className methodName:(NSString *)methodName withArguments:(NSArray *)arguments

Parameters

className

String identifing the class of the object containing the method to be tracked.

methodName

String identifing the method to be tracked.

arguments

The values of the arguments of this method call. This parameter is optional and may be nil. Additionally, you are free to send only a subset of the actual arguments.

Return Value

An object that must be passed to endCall:.

Note:

Discussion

This method is useful for tracking execution of methods originating from non-iOS systems where ‘receiver’ & ‘selector’ are not defined. Otherwise its function is similar to beginCall:receiver selector:selector arguments:arguments.

Warning: className must not be nil.

Warning: methodName must not be nil.

Declared In

ADEumInstrumentation_interfaces.h

+ endCall:withValue:

Call this method right before returning from a method to finish tracking the method invocation.

+ (void)endCall:(id ADEUM_NULLABLE)call withValue:(id ADEUM_NULLABLE)returnValue

Parameters

call

The object returned from beginCall:Selector:withArguments:.

returnValue

The return value of the method. This is optional, and may be nil.

Declared In

ADEumInstrumentation_interfaces.h

+ endCall:

Call this method right before returning from a method to finish tracking the method invocation.

+ (void)endCall:(id ADEUM_NULLABLE)call

Parameters

call

The object returned from beginCall:Selector:withArguments:.

Discussion

Equivalent to endCall:call withValue:nil.

Declared In

ADEumInstrumentation_interfaces.h

Timing events

+ startTimerWithName:

Starts a timer for tracking a user-defined event with a duration.

+ (void)startTimerWithName:(NSString *ADEUM_NULLABLE)name

Parameters

name

The name of the timer, which will determine the name of the corresponding metric. Generally, timers that are logically separate should have distinct names.

Discussion

If this method is called multiple times without a corresponding call to stopTimerWithName, every call after the first will reset the timer.

Timer name should contain only alphanumeric characters and spaces. Illegal characters shall be replaced by their ASCII hex value.

Warning: pre-4.3 agents threw NSException on illegal characters.

Declared In

ADEumInstrumentation_interfaces.h

+ stopTimerWithName:

Stops a timer for tracking a user-defined event with a duration.

+ (void)stopTimerWithName:(NSString *ADEUM_NULLABLE)name

Parameters

name

The name of the timer, which will determine the name of the corresponding metric. Generally, timers that are logically separate should have distinct names.

Discussion

If you haven’t called startTimerWithName with the given name before calling this method, this method has no effect.

Timer name should contain only alphanumeric characters and spaces. Illegal characters shall be replaced by their ASCII hex value.

Warning: pre-4.3 agents threw NSException on illegal characters.

Declared In

ADEumInstrumentation_interfaces.h

Reporting metrics

+ reportMetricWithName:value:

Reports the value of a custom metric.

+ (void)reportMetricWithName:(NSString *ADEUM_NULLABLE)name value:(int64_t)value

Parameters

name

The name of the metric.

value

The value of the metric.

Discussion

Metric name should contain only alphanumeric characters and spaces. Illegal characters shall be replaced by their ASCII hex value.

Warning: pre-4.3 agents threw NSException on illegal characters.

Declared In

ADEumInstrumentation_interfaces.h

Breadcrumbs tracking for crash reports

+ leaveBreadcrumb:

Records the value of breadcrumb and assigns it a current timestamp.

+ (void)leaveBreadcrumb:(NSString *ADEUM_NULLABLE)breadcrumb

Parameters

breadcrumb

The value of breadcrumb.

Discussion

Call this method when something interesting happens in your application. If your application crashes at some point in the future, the breadcrumb will be included in the crash report, to help you understand the problem. Each crash report displays the most recent 99 breadcrumbs.

Warning: The breadcrumb will not be recorded if it is nil or the empty string. The breadcrumb will be truncated if it is longer than 2048 characters.

Declared In

ADEumInstrumentation_interfaces.h

+ leaveBreadcrumb:mode:

Records the value of breadcrumb and assigns it a current timestamp.

+ (void)leaveBreadcrumb:(NSString *ADEUM_NULLABLE)breadcrumb mode:(ADEumBreadcrumbVisibility)mode

Parameters

breadcrumb

The value of breadcrumb.

mode

The visibility mode, which is either ADEumBreadcrumbVisibilityCrashesOnly or ADEumBreadcrumbVisibilityCrashesAndSessions.

Discussion

Call this method when something interesting happens in your application. The breadcrumb will be included in different reports depending on the ‘mode’. Each crash report displays the most recent 99 breadcrumbs.

Warning: The breadcrumb will not be recorded if it is nil or the empty string. The breadcrumb will be truncated if it is longer than 2048 characters.

Warning: mode must be either ADEumBreadcrumbVisibilityCrashesOnly or ADEumBreadcrumbVisibilityCrashesAndSessions. If an invalid value is provided, it will default to ADEumBreadcrumbVisibilityCrashesOnly.

Declared In

ADEumInstrumentation_interfaces.h

UserData tracking

+ setUserData:value:

Sets the value of the specified key to the specified string value.

+ (void)setUserData:(NSString *ADEUM_NULLABLE)key value:(NSString *)value

Parameters

key

The key with which to associate with the value.

value

The non-nil NSString value to store.

Discussion

Notes

  • All UserData interfaces are type specific and maintain a separate key name space. This means that both +setUserDataBoolean:value: and +setUserDataLong:value: can use a key of @"foo".

  • UserData can be used to relay any information available to the programmer.

  • The keys for this method are global and must be unique across your application. Re-using the same key for the same UserData type overwrites the previous value.

Warning: Both the key and the value will if be truncated if they are longer than 2048 characters.

Declared In

ADEumInstrumentation_interfaces.h

+ removeUserData:

Removes the NSString value associated with key.

+ (void)removeUserData:(NSString *ADEUM_NULLABLE)key

Parameters

key

The key whose value you want to remove.

Declared In

ADEumInstrumentation_interfaces.h

+ setUserDataLong:value:

Sets the value of the specified key to the specified signed 64-bit integer value.

+ (void)setUserDataLong:(NSString *ADEUM_NULLABLE)key value:(int64_t)value

Parameters

key

The key with which to associate with the value.

value

Signed 64-bit integer value to store.

Declared In

ADEumInstrumentation_interfaces.h

+ removeUserDataLong:

Removes the signed 64-bit data value associated with key.

+ (void)removeUserDataLong:(NSString *ADEUM_NULLABLE)key

Parameters

key

The key whose value you want to remove.

Declared In

ADEumInstrumentation_interfaces.h

+ setUserDataBoolean:value:

Sets the value of the specified key to the specified Boolean value.

+ (void)setUserDataBoolean:(NSString *ADEUM_NULLABLE)key value:(BOOL)value

Parameters

key

The key with which to associate with the value.

value

The boolean value to store.

Declared In

ADEumInstrumentation_interfaces.h

+ removeUserDataBoolean:

Removes the boolean data value associated with key.

+ (void)removeUserDataBoolean:(NSString *ADEUM_NULLABLE)key

Parameters

key

The key whose value you want to remove.

Declared In

ADEumInstrumentation_interfaces.h

+ setUserDataDouble:value:

Sets the value of the specified key to the specified double value.

+ (void)setUserDataDouble:(NSString *ADEUM_NULLABLE)key value:(double)value

Parameters

key

The key with which to associate with the value.

value

The double value to store. The value has to be a finite real number. The use of NAN, +INF or -INF may lead to undefined behavior.

Declared In

ADEumInstrumentation_interfaces.h

+ removeUserDataDouble:

Removes the double data value associated with key.

+ (void)removeUserDataDouble:(NSString *ADEUM_NULLABLE)key

Parameters

key

The key whose value you want to remove.

Declared In

ADEumInstrumentation_interfaces.h

+ setUserDataDate:value:

Sets the value of the specified key to the specified NSDate object.

+ (void)setUserDataDate:(NSString *ADEUM_NULLABLE)key value:(NSDate *)value

Parameters

key

The key with which to associate with the value.

value

The non-nil NSDate object to store.

Discussion

Note

The Date value will be stored as a signed 64-bit integer representing milliseconds since 1970 (epoch time) UTC.

Declared In

ADEumInstrumentation_interfaces.h

+ removeUserDataDate:

Removes the Date data value associated with key.

+ (void)removeUserDataDate:(NSString *ADEUM_NULLABLE)key

Parameters

key

The key whose value you want to remove.

Declared In

ADEumInstrumentation_interfaces.h

Screenshot Support

+ takeScreenshot

Takes a screenshot of the current app’s window.

+ (void)takeScreenshot

Discussion

If screenshots are disabled through screenshotsEnabled or through the controller UI, then this method does nothing. This will capture everything, including personal information, so you must be cautious of when to take the screenshot. These screenshots will show up in the Sessions screen for this user. The screenshots are taken on the main application thread as soon as safe to do so. The screenshots are compressed, and only non-redundant parts are uploaded, so it is safe to take many of these without impacting performance of your application.

Declared In

ADEumInstrumentation_interfaces.h

+ unblockScreenshots

Unblocks screenshot capture if it is currently blocked. Otherwise, this has no effect.

+ (void)unblockScreenshots

Discussion

If screenshots are disabled through ADEumMAgentConfiguration.screenshotsEnabled or through the controller UI, this method has no effect.

If screenshots are set to manual mode in the controller UI, this method unblocks for manual mode only.

WARNING: This will unblock capture for the entire app.

The user is expected to manage any possible nesting issues that may occur if blocking and unblocking occur in different code paths.

Declared In

ADEumInstrumentation_interfaces.h

+ blockScreenshots

Blocks screenshot capture if it is currently unblocked. Otherwise, this has no effect.

+ (void)blockScreenshots

Discussion

If screenshots are disabled through ADEumMAgentConfiguration.screenshotsEnabled or through the controller UI, this method has no effect.

WARNING: This will block capture for the entire app.

The user is expected to manage any possible nesting issues that may occur if blocking and unblocking occur in different code paths.

Declared In

ADEumInstrumentation_interfaces.h

+ screenshotsBlocked

whether screenshot capture is blocked

+ (BOOL)screenshotsBlocked

Return Value

whether screenshot capture is blocked

Declared In

ADEumInstrumentation_interfaces.h

Session Frame Support

+ startSessionFrame:

Starts a Session Frame

+ (ADEumSessionFrame *)startSessionFrame:(NSString *)name

Parameters

name

This is the name for the Session Frame that will appear in the UI.

Return Value

An ADEumSessionFrame object is returned which should be retained for further operations.

Availability

50.1

Declared In

ADEumInstrumentation_interfaces.h

NSError Reporting

+ reportError:

Report an error (Deprecated: Report error without explicitly passing severity is deprecated. Use reportError:withSeverity: instead.)

+ (void)reportError:(NSError *)error

Parameters

error

Standard iOS NSError object. If nil, no report is made

Discussion

Creates an error report, with the contents of the passed in NSError object as well as a stack trace of the current machine state.

Default severity level ADEumErrorSeverityLevelWarning will be used.

Declared In

ADEumInstrumentation_interfaces.h

+ reportError:withSeverity:andStackTrace:

Report an error

+ (void)reportError:(NSError *)error withSeverity:(ADEumErrorSeverityLevel)severity andStackTrace:(BOOL)stacktrace

Parameters

error

Standard iOS NSError object. If nil, no report is made

severity

The error severity level.

stacktrace

YES to indicate that a stack trace should be included, otherwise NO.

Discussion

Creates an error report, with the contents of the passed in NSError object as well as an optional stack trace of the current machine state, also with error severity level defined.

Valid severity levels are:

  • ADEumErrorSeverityLevelInfo
  • ADEumErrorSeverityLevelWarning
  • ADEumErrorSeverityLevelCritical

Warning: If an invalid severity value is provided, it will default to ADEumErrorSeverityLevelWarning.

Warning: Values passed in error.userInfo which cannot be serialized to JSON will be removed and list of this items will be added as NonSerializableKeys.

Declared In

ADEumInstrumentation_interfaces.h

+ reportError:withSeverity:

Report an error

+ (void)reportError:(NSError *)error withSeverity:(ADEumErrorSeverityLevel)severity

Parameters

error

Standard iOS NSError object. If nil, no report is made

severity

The error severity level.

Discussion

Creates an error report, with the contents of the passed in NSError object as well as a stack trace of the current machine state, also with error severity level defined.

Valid severity levels are:

  • ADEumErrorSeverityLevelInfo
  • ADEumErrorSeverityLevelWarning
  • ADEumErrorSeverityLevelCritical

Warning: If an invalid severity value is provided, it will default to ADEumErrorSeverityLevelWarning.

Warning: Values passed in error.userInfo which cannot be serialized to JSON will be removed and list of this items will be added as NonSerializableKeys.

Declared In

ADEumInstrumentation_interfaces.h

+ createCrashReport:type:

Creates a crash report of the given crash dump. This crash report will be reported to collector when application restarts.

+ (int)createCrashReport:(NSString *)crashDump type:(NSString *)type

Parameters

crashDump

Json string of the crash dump.

type

Crash report type, only “clrCrashReport” is supported for now.

Return Value

status, 0 means no error.

Discussion

This is an internal interface and subject to change without notice.

Declared In

ADEumInstrumentation_interfaces.h

+ startNextSession

Starts next session and ends the current session. The session started using this API may be ended by inactivity timeout set in the Application Configuration, before the next call to this API. This API makes some practical assumptions about session lengths among end users. Excessive use of this API will cause sessions to be throttled (excessive use is >10 calls per minute per agent, subject to change)

+ (void)startNextSession

Declared In

ADEumInstrumentation_interfaces.h

+ shutdownAgent

Stops the sending of beacons to the collector. No data will come from this agent while shut down. All other activities of the agent continue, just the sending of data is disabled.

+ (void)shutdownAgent

Declared In

ADEumInstrumentation_interfaces.h

+ fetchOriginalSessionObjectFrom:

When passed an object derived from ADEumBaseWrapper, such as ADEumURLSessionDelegate or ADEumURLSession, it will return the original object prior to wrapping. This is usually used when the original object was extended is some way prior to the call and was modified during the call.

+ (id)fetchOriginalSessionObjectFrom:(id ADEUM_NULLABLE)wrappedObject

Parameters

wrappedObject

The wrapped object in question.

Return Value

Original object in its original type if the object passed in was wrapped.

Discussion

Warning: It is imperative that you only use this API for URLSession and URLSessionDelegate objects from within completion blocks or delegate calbacks. Behavior is undetermined in any other case and may cause a crash. Please contact AppDynamics support if you are unclear on use of this API.

Warning: This API call should only be used in instances where you need to access the underlying object that was modified during the call.

Declared In

ADEumInstrumentation_interfaces.h

+ restartAgent

Restarts the sending of beacons to the collector. Data will start flowing from the agent immediately. No change will occur if the shutdownAgent call and not been made.

+ (void)restartAgent

Declared In

ADEumInstrumentation_interfaces.h