trace Integration
apptrace (en)


ServicePilot trace-apptrace


# AppTrace

Overview

This package enables apptrace collection.

Description

ServicePilot can be sent web service performance statistics that are stored by this trace-apptrace package into a ServicePilot Apptrace data collection. These statistics can then be used to produce AppTrace statistics by querying this database using the trace-apptrace-query package.

Requirements

  • Network Flows - It is is necessary to ensure network connectivity between your apptrace collector and the ServicePilot Agent that will insert this data in the ServicePilot AppTrace data collection. In case of a network infrastructure using a firewall, all the ports below must be opened:

    • AppTrace data (by default UDP/9411 although this port is configurable): Between device sending AppTrace data and ServicePilot Agent
  • ServicePilot Requirements

    • ServicePilot Manager minimum version: 8.5
    • ServicePilot Agent minimum version: 8.5 installed and configured

Installation

Before adding a resource to monitor, make certain that all pre-requisites are in place and if a ServicePilot Agent is required, that it is communicating correctly with the ServicePilot Manager.

Add resource using Views Configuration web interface

  1. As an administrative user of ServicePilot, open the ServicePilot web interface.
  2. Navigate to Administration. The Configuration > Views web page will open.
  3. Click on the view in which to place the new resource in the Views hierarchy on the left of the interface. The View editor section will show the existing view contents.
  4. From the Packages list on the right of the interface, click and drag the trace-apptrace package into the View editor and let go.
  5. The Resource properties dialog box will open to allow resource configuration.
  6. Click OK to close the Resource properties dialog box. Note that the dialog box will not close if required parameters are not set.
  7. Click Save to apply the new resource to ServicePilot configuration.

License

Object Type License object Consumed Condition
AppTrace Collector 1

Key field notes

  1. In the Policies tab, specify the policy or policies to apply to the resource

  2. Basic Parameters tab:

    1. Trace Port: The UDP port on which to accept apptrace data

Notes

The format of the UDP packets to send to the Trace Port opened by the ServicePilot Agent is as follows:

trace?traceid={traceid}&name={name}&error={error}&parentid={parentid}&parentservicename={parentservicename}&parent_ipv4={192.168.1.1}&duration={60}&ipv4_1={192.168.1.1}&port_1={80}&servicename_1={servicename_1}&timestamp_1={timestamp_1}&value_1={value_1}&ipv4_2={192.168.2.2}&port_2={80}&servicename_2={servicename_2}&timestamp_2={timestamp_2}&value_2={value_2}&http_host={http_host}&http_method={http_method}&http_path={http_path}&http_url={http_url}&http_status_code={200}&http_request_size={500}&http_response_size={500}&client_username={client_username}&client_ipv4={192.168.10.10}&client_port={4567}&client_servicename={client_servicename}

This text string is UTF8 encoded and each field value should be URI escaped.

The following table gives notes for each field:

Apptrace collection field name Field Type Notes
traceid Text Trace Identifier
name Text Name
error Positive Integer HTTP Error Text, if an error status code is returned
parentid Text Trace Parent Identifier
parentservicename Text Trace Parent Service Name
parent_ipv4 IPv4 Address Trace Parent IP Address
duration Positive Integer Duration in milliseconds
ipv4_1 IPv4 Address Request Service IP Address
port_1 IPv4 Port Request Service IP Port
servicename_1 Text Request Service Name
timestamp_1 UTC Timestamp (YYYY-mm-dd HH:MM:SS.000) Request Service Timestamp
value_1 Text Request Service Value
ipv4_2 IPv4 Address Response Service IP Address
port_2 IPv4 Port Response Service IP Port
servicename_2 Text Response Service Name
timestamp_2 UTC Timestamp (YYYY-mm-dd HH:MM:SS.000) Response Service Timestamp
value_2 Text Response Service Value
http_host Text HTTP Hostname
http_method HTTP Method in lower case (get, post) HTTP Method
http_path Text HTTP Path starting with /
http_url Text HTTP URL
http_status_code Positive Integer HTTP Status Code
http_request_size Positive Integer HTTP Request Size in Bytes
http_response_size Positive Integer HTTP Response Size in Bytes
client_username Text Client Username
client_ipv4 IPv4 Address Client IP Address
client_port IPv4 Port Client IP Port
client_servicename Text Client Service Name