ADEumInstrumentation Class Reference
Inherits from | NSObject |
---|---|
Declared in | ADEumInstrumentation_interfaces.h |
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 |
Return Value
An object that must be passed to endCall:
.
Discussion
Warning: receiver
must not be nil
.
Warning: selector
must not be nil
.
See Also
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
.
See Also
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 |
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
.
See Also
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 |
---|---|
returnValue |
The return value of the method. This is optional, and may be |
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 |
---|
Discussion
Equivalent to endCall:call withValue:nil
.
See Also
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 |
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 akey
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 |
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
+ 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
+ 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. Returns nil otherwise.
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 unsupported in any other use 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