Configure .NET Agent HTTP Client Correlation and HTTP Backend URL Path Naming

Path groups are named groupings of web service HTTP client requests that you define in terms of an HTTP backend URL path prefix.
apmdevops106
Path groups
 are named groupings of web service HTTP client requests that you define in terms of an HTTP backend URL path prefix.
3
2
HTTP Client Correlation
.NET agent client correlation starts with a page request from server to server. An instrumented server makes a client call to another server or an agent or a public web service. Therefore, the calling server is known as the 
client
, although technically the server is not actually a client. The server is instrumented to see outgoing request calls. When a call goes to another server that is also instrumented by an agent, then the call can be correlated.
These three .NET libraries are used in .NET agent HTTP client correlation framework:
  • System.Net.HttpWebRequest
  • System.Web.WebClient
  • System.Net.Http.HttpClient
HTTP Backend Path Group Naming
You can configure a set of .NET HTTP Backend path group properties to monitor the performance of outgoing HTTP queries that your  .NET applications make. The HTTP backends data displays as standard BlamePoint metrics under the Backends|WebService at {protocol}_//{host}:{port} Investigator node. Together these properties capture the HTTP method and the query parameters being used in transaction traces. You can configure error snapshots to be generated whenever an HTTP 4XX or 5XX response code is received.
These introscopeAgent.profile HTTP backend path group properties work together:
introscope.agent.backendpathgroup.keys=default introscope.agent.backendpathgroup.group.default.pathprefix=* introscope.agent.backendpathgroup.group.default.format={path_delimited:/:0:5}
With this configuration, the default HTTP backend paths display in an HTTP backend path group. Typically HTTP backend paths display under the Metric Browser 
Backends|WebService at {protocol}_//{host}_{port}|Paths
 node. 
To capture and group more path details for the various URLs, configure the URL path groups in the agent profile.
Using HTTP Backend Path Groups
The metrics for each path group are aggregated under the 
Backends|WebService at <
protocol
>_//<
host
>_<
port>
|Paths
 node in the Investigator metric browser tree. By default, all HTTP backend URL paths are assigned to the 
Default
 group. With path groups, you can determine how many requests are invoked from the HTTP backend. You can then diagnose performance problems.
The following example shows three HTTP backend URL paths as they would display in the metric browser tree:
Backends|WebService at http_//host_port|Paths|alphaHTTPClientPost
Backends|WebService at http_//host_port|Paths|betaHTTPClientGet
Backends|WebService at http_//host_port|Paths|Default
This example shows how three path groups are defined in the agent profile:
introscope.agent.backendpathgroup.keys=alphaHTTPClientPost,betaHTTPClientGet,default
introscope.agent.backendpathgroup.group.alphaHTTPClientPost.pathprefix=/testWar/helloWorld/alphaHTTPClientPost
introscope.agent.backendpathgroup.group.alphaHTTPClientPost.format=alphaHTTPClientPost
introscope.agent.backendpathgroup.group.betaHTTPClientGet.pathprefix=/testWar/helloWorld/betaHTTPClientGet
introscope.agent.backendpathgroup.group.betaHTTPClientGet.format=betaHTTPClientGet
introscope.agent.backendpathgroup.group.default.pathprefix=*
introscope.agent.backendpathgroup.group.default.format=Default
Define Keys for Path Groups
The 
introscope.agent.backendpathgroup.keys
 Delimiter characters in the agent profile define a list of the keys of all the path groups. The key for a path group is referenced in other property definitions that declare an attribute of the path group.
introscope.agent.backendpathgroup.keys=alpha,beta,default
Each entry has two properties that are used to define the path and match output results as follows:
introscope.agent.backendpathgroup.group.[
Key
].pathprefix
introscope.agent.backendpathgroup.group.[
Key
].format
The [
Key
] entries are used to locate the named property. The 
[
Key
]
 value corresponds with the 
introscope.agent.backendpathgroup.keys
 property as shown:
introscope.agent.backendpathgroup.keys=key_one,key_two,key_three
introscope.agent.backendpathgroup.group.key_one.pathprefix
introscope.agent.backendpathgroup.group.key_one.format
introscope.agent.backendpathgroup.group.key_two.pathprefix
introscope.agent.backendpathgroup.group.key_two.format
introscope.agent.backendpathgroup.group.key_three.pathprefix
introscope.agent.backendpathgroup.group.key_three.format
You can define path groups so some paths fall into multiple groups. In this situation, the order in which you list the keys for the path groups in the 
introscope.agent.backendpathgroup.keys
 property is important. Be sure that the path group with the narrower membership precedes the path group with broader membership.
Define Membership of Each Path Group
The 
introscope.agent.backendpathgroup.group.default.pathprefix
 property specifies a pattern against which the path prefix of a path is matched. The matching defines which requests fall within the path group.
Example: Map a Group Key to a Path Prefix
This property definition assigns all requests in which the path portion of the path starts with 
/testWar
 to the path group whose key is 
alphaHTTPClientPost
:
introscope.agent.backendpathgroup.group.alphaHTTPClientPost.pathprefix=/testWar
Requests that match the specified pathprefix include:
http://backend.ca.com:1234/testWar/example/post.htm
You can use the asterisk symbol (*) as a wildcard in 
pathprefix
 properties.
Define the Name for a Path Group
The
 introscope.agent.backendpathgroup.group.<key>.format
 property determines the names under which response time metrics for a path group are generated.
Typically, the
 introscope.agent.backendpathgroup.group.<key>.format
 property is used to assign a text string as the name for a path. The following example causes metrics for the path group with key 
alpha
 to appear in the metric browser tree under the name 
Alpha Group
:
introscope.agent.backendpathgroup.group.alpha.format=Alpha Group
(Optional) Advanced Naming Techniques for Path Groups
You can derive a path group name from request elements such as the protocol, or from a substring of the request path. This section describes advanced forms of the 
introscope.agent.backendpathgroup.group.<key>.format 
property.
Use a Substring of the Request Path as a Path Group Name
You can organize statistics for a path group under names that reflect a substring of the path portion of request paths. Define 
introscope.agent.backendpathgroup.group.<key>.format 
as shown:
introscope.agent.backendpathgroup.group.
alpha
.format=
{path_substring:
m
:
n
}
Where 
m
 is the index of the first character, and 
n
 is one greater than the index of the last character. String selection operates like the 
java.lang.String.substring()
 method. For example, for the following setting:
introscope.agent.backendpathgroup.group.alpha.format=
{path_substring:0:3}
With this URL:
http://www.buyitall.com/userid,sessionid/pageid
Statistics would appear under: 
/us.
The path grouping works only on the path part of the URL. In the previous example it is: 
/testWar/helloWorld/alphaHTTPClientPost
.
Use a Delimited Portion of the Request Path as a Path Group Name
To organize statistics for a path group under names that reflect a character-delimited portion request path, define the 
introscope.agent.backendpathgroup.group.alpha.format
 property as shown:
introscope.agent.backendpathgroup.group.
alpha
.format=
{path_delimited:delim_char:m:n}
The 
delim_char
 character delimits the segments in the path. The 
m
 value is the index of the first segment to select, and the 
n
 value is one greater than the index of the last segment to select. For example, given this setting:
introscope.agent.backendpathgroup.group.
alpha
.format={path_delimited:/:2:4}
Statistics for the requests of this form:
http://www.buyitall.com/userid,sessionid/pageid
Appear under the metric node 
/pageid
.
Follow these rules:
  • Delimiter characters count as a segment. In the previous example, the delimiter characters is the forward slash (/).
  • Segment counts start at 0.
  • Path grouping works only on the path part of the URL. In the previous example, the path part of the URL is 
    /userid,sessionid/pageid
    .
The segments as delimited by the slash character in the path example are:
0=
/
, 1=
userid,sessionid
, 2=
/
, and 3=
pageid
You can specify multiple delimiters as necessary. For example, given this setting:
introscope.agent.backendpathgroup.group.
alpha
.format={path_delimited:/,:3:4}
Statistics for requests of the form that is shown in the previous example appear under the 
sessionid
 node. The segments as delimited by the slash and the comma in the path example are:
0=
/
, 1=
userid
, 2=„
,
 3=
sessionid
, 4=
/
, and 5=
pageid
Limit the Number of Unique Backend Path URL Group Metrics
You can use the 
introscope.agent.urlgroup.backend.url.clamp
 property to to limit the number of unique backend path group URL metrics that the .NET agent creates. When the number of new backend path groups reaches the set value, metrics for new backend path group URLs display in the Metric Browser. They display under the 
Backends|WebService at {protocol}_//{host}_{port}|Paths|
Default
 node. This property helps to prevent metric explosions.
To collect meaningful metrics from the 
Backends|WebService at {protocol}_//{host}_{port}|Paths
 node, set up backend path groups that are relevant to your deployment.
Follow these steps:
  1. Open the IntroscopeAgent.profile in the <Agent_Home> directory in a text editor.
  2. Go to the URL Grouping Configuration section.
  3. Configure the 
    introscope.agent.urlgroup.backend.url.clamp
     property.
    The default is 5 backend path group URLs.
  4. Save and close the file.
    No managed application restart is needed.
Backend Path Group Naming
These backend path group properties work together when all are set to their default introscopeAgent.profile settings as shown:
introscope.agent.backendpathgroup.keys=default
introscope.agent.backendpathgroup.group.default.pathprefix=*
introscope.agent.backendpathgroup.group.default.format={path_delimited:/:0:5}
introscope.agent.urlgroup.backend.url.clamp=5
With this configuration, the default backend paths display in a backend path group. The group is named for and located two segments after the protocol in the backend path. 
For example, typically backend paths are listed under the 
Backends|WebService at {protocol}_//{host}_{port}|Paths
 node. When the number of backend path groups that are created across all the .NET applications reaches the 
introscope.agent.urlgroup.backend.url.clamp
 setting, any new backend paths display under the 
Backends|WebService at {protocol}_//{host}_{port}|Paths|
Default
 node.