End-User Endpoints Monitoring
Contents
apmdevops97
Contents
End-User Endpoints Monitoring depends on a compatible end-user monitoring component. The compatible component externally provides CA APM Business Transaction context and metadata for each request to an application that CA APM monitors. CA Mobile App Analytics (CA MAA) is designed to provide this type of information to CA APM when enabled. CA MAA provides facilities to instrument native mobile apps on handheld computing devices for operating systems such as Android and iOS. The Business Transaction context moves from CA MAA to CA APM to show the end-user experience based on the originating device platform in APM WebView. Monitoring this data helps you to identify performance problems for a mobile app at any time during its execution. Early detection of a problem helps you to address it before degraded performance affects the end users.
CA MAA is available as a CA SaaS product or as an on-premises solution that is a part of the CA Mobile DevOps portfolio.
As an application owner, perform the following steps:
- Understand how business transaction naming works.
- View app analytics, such as statistics and crashes, in CA MAA.
Verify the End-User Endpoints Monitoring Prerequisites
Before you implement End-User Endpoints Monitoring, verify the following prerequisites:
- You are using a compatible monitoring solution such as CA MAA.
- For the CA SaaS implementation of CA MAA, you have a tenant account and CA MAA administrator login credentials.
- For the CA MAA on-premises solution, you have CA MAA administrator login credentials.
- Your CA APM implementation includes:
- WebView
- A deployed Java agent that monitors the backend application with which the native mobile app communicates.
How Business Transaction Naming Works
The end-user monitoring solution, CA MAA SDK, injects a header parameter to the HTTP request. This parameter names the mobile business service and transaction that the request belongs to. A single header parameter that is named x-apm-bt encodes data that is relevant to the transaction. The header parameter consists of two segments that a dollar sign ($) separates. The two segments consist of several semicolon-separated attributes. The second segment of the parameter contains the identifying attributes of the transaction and follows a specified order. The total parameter value size is limited. The agent ignores x-apm-bt parameters that exceed the limit or are malformed. Requests that include such invalid parameters are treated as APM business transactions (transactions that agents and CEM TIMs monitor).
Agents do the following actions with the header information:
- Receive an HTTP request that is annotated with the x-apm-bt parameter.
- Treat the request as a matched Business Transaction component.
- Create or update relevant metrics and APM data model elements. Mobile source-related attributes are parsed from the segmented parameter values and are stored as business transaction properties.
The header parameter structure is as follows:
x-apm-bt: t=<MAA-TenantID>;d=<UDID>;v=<MAA-SDK-Version>;n=<NetworkNAME>;l=<LinkType>;g=<GeographicalLocation>;a=<AppNAME>$bs=<BusinessServiceName>;bt=<BusinessTransactionName>;p=<PlatformNAME>;pv=<PlatformVersion>
Example: HTTP Header Parameter
x-apm-bt: t=4F2504E0-4F89-9B0C-0305E82C2301;d=2b6f0cc904d137be2e1730235f5664094b831186;v=1.0;n=ATT;l=3g;g=36.9125, 30.6897222;a=Trade App$bs=Trade App;bt=Buy Options;p=iOS;pv=7.1
Attribute Name | Description | Required |
t | Identifies the CA SaaS tenant. | No |
d | Holds the unique ID of the originating device/hardware. | No |
v | Identifies the version of the monitoring solution (that is, CA MAA SDK) that created this header parameter. | No |
n | Identifies the network provider that the originator device is connected to at the time of the request (Verizon, AT&T, and so on). | No |
l | Identifies the network connection type that the originator device was utilizing at the time of the request (WiFi, LTE, 3g, and so on). | No |
xbtt | Defines the type of this external business transaction. Possible values are: [t1, t2]. | No |
p | Identifies the device/hardware operating system (iOS7, Android, and so on). | No |
pv | Identifies the device/hardware operating system version (4, 7.1, and so on). | No |
g | Specifies comma-separated values for longitude and latitude, indicating where the transaction was originated. | No |
bs | Holds the parent Business Service Name for this request (that is, CA MAA determines the business service name and is either a copy of the mobile app name or a literal name that the app author specifies depending on the MAA instrumentation method used). | Yes |
bt | Holds the parent Business Transaction Name for this request. APM constructs an identifier using this name, the business service name, and the platform specifics. APM aggregates metrics for all requests that are marked with the same identifier {p, pv, bs, bt}. | Yes |
a | Identifies the app/application name (that is, the app name specified by the CA MAA SDK). | No |
The {p, pv, bs, bt} attributes together identify a business transaction. If available, the operating system version is gathered in full, however business transactions are named according to the operating system major version. A full operating system version however is available in transaction traces. If a required attribute is missing, the header is ignored and the request is treated as a standard business transaction.
Integrate your Mobile Apps with CA MAA
CA MAA annotates the HTTP calls that mobile apps make with an External APM Business Transaction identifying header attribute (x-apm-bt). End-User Endpoints Monitoring then processes the marked HTTP requests to identify the mobile transaction that these requests belong to. When the Introscope agents encounter this header parameter, the header value identifies the mobile business transaction identifier. Therefore, agents treat the request as if it belongs to a matched business transaction.
You integrate CA MAA SDK with the apps that you want to monitor for performance. In CA MAA, you register a mobile app and instrument a native mobile application using the CA MAA SDK to:
- Integrate your iOS apps with CA MAA.
- Integrate your Android apps with CA MAA.
Follow these steps:
- Log in to the CA MAA Administration Console and register your app.CA MAA provides an iOS and an Android SDK to enable iOS and Android app developers to integrate CA MAA into their apps.
- Following the instructions in CA MAA, do the following tasks:
- Download the CA MAA SDK that corresponds to your device platform.
- Include the CA MAA SDK into your app build environment.
- Test your app.
For more information, see the
CA Mobile App Analytics Integration Guide
.Monitor the End-User Experience
All end-user business services and transactions are represented in a similar manner in WebView. This representation provides a comprehensive view of how transactions are performing from origin to the APM-monitored backends.
Follow these steps:
- In WebView, click Investigator, Triage Map.A tree shows a hierarchical view of your system with the following high-level nodes:
- By Business Service-- A business-centric catalog of your business services and transactions.
- By Frontend-- A frontend-centric catalog of your applications.A frontend is a logical grouping of components of your application that is exposed to the outside world. Frontends often access backend systems and performance measurements as experienced by a frontend. The backend systems are listed under the “backend calls" of the said frontend.Each application has two child nodes:
- Health-- Aggregated metrics of the frontend across the physical locations.
- Backend Calls-- Metrics for calls to other elements supporting the selected frontend.
- View the following nodes in the tree:
- The business service, for example: Book Store.
- The mobile business transaction name, and operating system name and version, for example: Login via Android 4.Mobile app business transactions that have the same operating system definition, but that have different minor version numbers appear as a single number. Minor version numbers aggregate to a single number, for example, 4.1 and 4.2 display as 4.For each business transaction, the standard metrics appear. For mobile business transactions, the following extra metric appears:Responses Per Interval forNetwork_Provider-- The number of requests that are completed during a specified time slice for each network provider, for example:Mobile Responses Per Interval for VerizonMobile Responses Per Interval for AT&TYou can use EndUserEndpoints.pbd to configure the metric naming, and the attribute that is used to create separate response counting metrics.
- Click a business transaction node of interest.The Triage Map shows a visual display of auto-discovered components and dependencies for applications that agents are monitoring:
- Arrow connectors represent relationships between map components. Connections between a selected component and its dependencies are emphasized with darkened lines. The corresponding map element is highlighted with a shadow, and its dependencies appear in full color. Components that are not participating in the selected element appear dimmed.
- The mobile business transaction node shows:
- The mobile operating systems, such as Android and iOS.
- The mobile business transaction name, as defined by the app author or CA MAA SDK.
- Mouseover a mobile transaction node in the map or a graph metric line of interest in the metric overview.Tooltips show information according to your selection.
- Map element tooltips show the alert level and metric information.
- Graph line tooltips show the metric details, and threshold tooltips display the threshold value of the alert.
- View agent locations and resource locations.The Locations table lists physical locations for agents or resources. Browse this list and look for metric spikes on individual hosts. This information helps you to identify outlier agents that do not necessarily move the aggregations significantly.
- View the health of an application:
- Right-click a component in the Triage Map and select View Health Metrics forName.The tree changes for the application you selected:
- To the Health node for By Frontends.
- To the Business Transaction Components node for By Business Service.
- Click the Health node or Backend Calls node under each application that is listed under By Frontend.Aggregated health metrics appear for the application.
- (Optional) Click Hide Alert Thresholds.All alert thresholds disappear from the charts. Clicking this button toggles between hiding and showing alert thresholds for all charts on the page.
View Individual Components in Trace View
Transaction traces record the metadata that the end-user monitoring solution passes (that is, CA MAA-specific attributes). View the transaction components in a graphical stack. You examine the components from top to bottom to understand the sequence of calls within a time period and evaluate performance. End-user monitoring metadata attributes are associated with the root component and their keys are prefixed with x-apm-bt.
Follow these steps:
- In WebView, click Tools, Transaction Tracer.You can also access this information through Tools, Historical Event Viewer, and running a query.
- Select a mobile transaction trace in the table.
- Click the Trace View tab in the lower pane.Note: In Live mode, Traces tab lists transaction trace events from the last 20 minutes. Transaction trace event older than 20 minutes are not displayed in live mode.The components for the selected transaction appear in a graphical stack display.
- In the agent status area, view information including:
- TimestampDisplays the start time, in the agent system clock, of the invocation of the root component.
- DurationDisplays the execution time of the root component in milliseconds.
- In the data viewer, examine the components in the graphical stack from top to bottom and evaluate the application performance.Tip:Click the right-facing blue triangle to expand the graphical display to show individual transaction components.The graphical stack view shows the following information:
- Each component in the transaction as a bar.
- Calling relationships between components -- The bars for components are displayed from top to bottom in calling order.
- Transaction sequence over time -- The placement of components from left to right indicates sequence. The relative wall clock time in milliseconds appears across the top of the transaction.
- Errors within transactions -- Red slices in the transaction graphical stack represent errors within transactions.
- Cross-process and cross-JVM transaction data -- CA APM uses a unique identifier, the correlation ID, to link traced frontend and backend transactions. The sequence is based on the order in which frontends call backends in a transaction. When multiple graphical stacks appear in the viewer, the system has found and traced related processes for the selected trace event. Processes that are traced from different agents appear in different shaded areas. By examining the linked components in a transaction trace, you can see whether a certain transaction left a process; and entered a different one. You can also get insight into which calls could be the source of slow and stalled transactions.
- Use the tab key to navigate from one component to another in the stack display.
- Zoom in and out of the display as needed using the Zoom slider in the upper-right corner. You can specify a value from 1 to 10. Each value in the slider multiplies the width of the graphical display by two. A value of 1 is the default.
- Mouseover a component to view a tooltip with more information.
- In the Component Details area, view the following information:Not all the information is available about deep transaction trace components.
View Analytics in CA MAA
CA MAA provides insight for performance and crashes of your mobile apps. Performance-related data provides analytics for memory, network, average latency, and so on. You can analyze the usage data based on numerous parameters, such as app version, geographical location, operating system, carrier information, and device information.
Follow these steps:
- Log in to the CA MAA Administration Console.
- In the left pane, tap ANALYTICS.
- Use the options to view analytics about:
- Overview
- Performance
- Crashes
- Usage
Configure the External Business Transaction Monitoring Properties
The External Business Transaction Monitoring properties configure the Java agent. This configuration matches CA APM business transactions to external business transactions provided by the end-user monitoring solution such as CA MAA. You can change the properties, for example, to clamp the total number of mobile business transactions.
This task is optional. Business transaction matching is enabled by default.
Follow these steps:
- Navigate to <Agent_Home>/core/config on the server for the application you want to monitor.This location is the default.
- Open the IntroscopeAgent.profile in a text editor.
- Go to this section:# External Business Transaction Monitoring properties
- Modify any of the following properties:
- introscope.agent.external.biz.enabledTurns on/off the External Business Transaction Monitoring feature.Default:true
- introscope.agent.external.biz.header.size.maxSpecifies the maximum data size for the External Business Transaction header parameter (x-apm-bt). The unit is 1 KB. A request with a parameter exceeding this limit is not processed as an External Business Transaction.Default:10
- introscope.agent.external.biz.bt.count.maxSpecifies the maximum number of External Business Transactions allowed. Resets the current External Business Transaction definition.Default:1000
- Save and close the IntroscopeAgent.profile file.Note:Changes take effect immediately and do not require the managed application to be restarted.
Configure the Probebuilder Directive File
The Probebuilder Directive file (EndUserEndpoints.pbd) provides tracer directives for End-User Endpoints Monitoring. You can use EndUserEndpoints.pbd to configure the metric naming, and the attribute that is used to create separate response counting metrics.
This task is optional. Transaction tracing is enabled by default.
Follow these steps:
- Navigate to the <Agent_Home>/core/config directory.
- Open the EndUserEndpoints.pbd file in a text editor.
- Set the properties according to the instructions in the file:############# # Flag intersection ############# SetFlag: ExternalBTAttributeNNewMode SetFlag: HttpServletTypeSpecificServiceExternalbtSingleTracing IdentifyTwoFlagIntersectionAsAggregateFlag: HttpServletTypeSpecificServiceTracing ExternalBTAttributeNNewMode HttpServletTypeSpecificServiceExternalbtSingleTracing ############################################################# # Network Provider-based Response Counter # # NOTES: # When available, the HTTP header attribute 'x-apm-bt' is parsed and AttributePerIntervalCounterDifferentInstances uses the network provider attribute (n) to create an additional response counter. ############################################################# SetTracerClassMapping: AttributePerIntervalCounterDifferentInstances com.wily.introscope.agent.external.biz.trace.SinglePerIntervalCounter com.wily.introscope.probebuilder.validate.MetricNameValidator SetTracerParameter: AttributePerIntervalCounterDifferentInstances nameformatter com.wily.introscope.agent.external.biz.util.HTTPSinglePerIntervalCounterFormatter TraceOneMethodWithParametersIfFlagged: HttpServletTypeSpecificServiceExternalbtSingleTracing service(Ljavax/servlet/http/HttpServletRequest;Ljavax/servlet/http/HttpServletResponse;)V AttributePerIntervalCounterDifferentInstances "Responses Per Interval for {value}" SetTracerParameter: AttributePerIntervalCounterDifferentInstances attributeKey n
- Save and close the file.
- Restart the application.
Disable External Business Transaction Monitoring
You can disable External Business Transaction Monitoring by configuring a property in the IntroscopeAgent.profile file.
Follow these steps:
- Navigate to <Agent_Home>/core/config on the server for the app you are monitoring.This location is the default.
- Open the IntroscopeAgent.profile file in a text editor.
- Set introscope.agent.external.biz.enabled=false.
- Save and close the file.The change takes effect immediately and does not require the managed application to be restarted.
Turn Off or On End-User Endpoints Monitoring
You can turn on or off or the External Business Transaction for End-User Endpoints Monitoring feature using the toggles pbd. This feature is enabled by default.
Follow these steps:
- Go to<Appserver_Home>/core/config directory or<Agent_Home>/core/config/systempbd directory.The locations depend on which file type (<appserver>-full.pbl or<appserver>-typical.pbl) the Java agent uses.
- Open either toggles-full.pbd or toggles-typical.pbd files:
- toggles-full.pbdProvides on/off switches in the form of TurnOn directives for the tracing that is provided in other directives files. Most tracer groups are turned on.
- toggles-typical.pbdProvides on/off switches in the form of TurnOn directives for the tracing that is provided in other directives files. Only a small section of tracer groups is turned on.
- Locate this section:# External Business Transaction for End User Endpoints Monitoring
- Uncomment or comment the following line according to the action you want:TurnOn: ExternalBTAttributeNNewMode
- Save and close the file.