Oracle Cloud Infrastructure Documentation

Trace and Span Attributes for APM Java Agent

The trace (root span) and span attributes in Trace Explorer are defined by tagging a span, which enable the effective monitoring of the various tiers of an application.

Attributes are key-value pairs attached to a span to provide additional information and context about the operation performed in the span. A trace has some trace only attributes as well as all the span attributes of the root span.

In Trace Explorer, you can use attributes to query and filter traces and spans. There are two types of attributes: Dimensions (string attributes) and Metrics (numeric attributes) which are available in the Attributes panel in Trace Explorer.

This section provides a complete list of the out-of-the-box attributes applicable to APM Java agent. The below table includes:

  • Name: Name of the attribute.
  • Description: Brief description of the attribute.
  • Trace/Span: Availability of the attribute. A attribute can be available for traces, spans, or both.
  • Type: Type of attribute: Dimension or Metric.
Name Description Trace/Span Type
ApmVersion The version of the Application Performance Monitoring agent. Trace and span attribute Dimension
Appserver The flag to indicate if an application server has been discovered. When the application server type is java-jmx or java-no-jmx, then this dimension is set to false. Trace and span attribute Dimension
AppserverDisplayPort The port number of the application server. The default is the lowest HTTPS port, if available, or the lowest HTTP port. Trace and span attribute Dimension
AppserverId The hash of significant application server resources, which indicates if there is resource change in the application server over time. Trace and span attribute Dimension
AppserverName The name of the application server. Trace and span attribute Dimension
AppserverPorts The port numbers of the application server. Usually, there is only one port number for the Oracle WebLogic server and multiple for the Apache Tomcat server. In case of multiple port numbers, the values are comma separated. Trace and span attribute Dimension
AppserverType The type of application server. For example: Weblogic or Tomcat. Trace and span attribute Dimension
AppserverVersion The version of the application server software. Trace and span attribute Dimension
ClassMethod The class name and method name where span observation occurred. Trace and span attribute Dimension
ClientIp

The IP of the client that invoked the Servlet via HTTP.

By default, the agent will check the X-FORWARDED-FOR request header for this information.

If it's not available, it will invoke the ServletRequest.getRemoteAddr method.

The default behavior can be updated using ProbeConfig.acml file from the APM Java Agent. (See capture_client_ip and client_ip_header parameters.)

This information is used for the GeoMap. Depending on what Client IPs are captured, configuring the Geo IP Mapping can help provide more accurate results.

Trace and span attribute Dimension
Component The component that generated the span from the https://opentracing.io/specification/conventions/ standard, with values such as JDBC, SERVLET, and BROWSER. Trace and span attribute Dimension
ContextRoot The context root of the monitored web application. Trace and span attribute Dimension
DbConnUrl The JDBC connection URL used to connect to the database. Trace and span attribute Dimension
DbOracleConnectionId The unique Net Oracle connection ID generated by the Oracle JDBC driver for each JDBC connection to the Oracle database. This attribute is supported on Oracle JDBC clients 21 and newer. Trace and span attribute Dimension
DbErrorSqlState The SQLState code returned by SQLException.getSQLState in error scenarios. Trace and span attribute Dimension
DbErrorVendorCode A number identifying the error that caused the SQLException instance to be thrown. Trace and span attribute Metric
DbOracleSessionId The Oracle Session ID of the executed statement. Trace and span attribute Dimension
DbOracleSqlId The Oracle SQL ID calculated from the executed SQL statement. Trace and span attribute Dimension
DbOracleSqlId1 In batch statement executions, the Oracle SQL ID calculated from the first executed SQL statement. Trace and span attribute Dimension
DbOracleSqlId2 In batch statement executions, the Oracle SQL ID calculated from the second executed SQL statement. Trace and span attribute Dimension
DbStatement The normalized SQL text executed by the JDBC statement. Trace and span attribute Dimension
DbStatement1 In batch statement executions, the normalized SQL text of the first executed JDBC statement. Trace and span attribute Dimension
DbStatement2 In batch statement executions, the normalized SQL text of the second executed JDBC statement. Trace and span attribute Dimension
DbStatementAdditionalFetchCount The number of round trips to the database to fetch additional result set rows not returned upon initial statement execution. Trace and span attribute Metric
DbStatementAdditionalFetchTime The time (in milliseconds) spent fetching additional result set rows from the database that were not returned upon initial statement execution. Trace and span attribute Metric
DbStatementExecTime The time (in milliseconds) spent on the initial statement execution and returning any initial rows. Trace and span attribute Metric
DbType The type of the database. Currently only 'sql' type databases are supported. Trace and span attribute Dimension
DbUser The underlying JDBC connection user. Trace and span attribute Dimension
DeploymentInfo The deployment information about the monitored web application. This can be displayed in two formats, depending on whether the deployment type is available:

<Deployment Name>; <Deployment File Name>

<Deployment Name>; <Deployment File Name>; <Deployment Type>

 Trace and span attribute Dimension
DisplayName The display name of the application server. Trace and span attribute Dimension
ECID The Oracle Execution Context ID. Span attribute Dimension
Error The span property that marks a span as "failed" with boolean value true, in case of an error. This indicates that the application considered the operation represented by the span failed. The default boolean value is false (no error). Trace and span attribute Dimension
ErrorObject A human-readable description of the error. Trace and span attribute Dimension
GenAIChatHistory The conversation history or context from previous interactions with the Generative AI model Span attribute Dimension
GenAICompartmentId The unique identifier for the compartment where the GenAI request is processed. Span attribute Dimension
GenAIEmbeddingsPerSentence Size of the vector embedding generated per sentence. Specific to the model used Span attribute Dimension
GenAIEmbedResponseId The unique identifier for the embedding response Span attribute Dimension
GenAIEmbedSentenceCount The number of sentences processed for embedding generation Span attribute Dimension
GenAIEmbedTruncate Strategy to truncate inputs that exceed model limits (e.g. NONE, START) Span attribute Dimension
GenAIFinishReason The reason why the model stopped generating the response (e.g. max token limit, stop sequence) Span attribute Dimension
GenAIFrequencyPenalty Penalises repetition of words depending on the frequency of the occurrence of words Span attribute Dimension
GenAIInputSentences The actual sentences or text chunks submitted for embedding Span attribute Dimension
GenAIIsEcho Boolean flag indicating if the prompt should be echoed back in the response Span attribute Dimension
GenAIMaxTokens The maximum number of tokens the model is allowed to generate in its response Span attribute Dimension
GenAIModelName The name of the Generative AI model being used for the request (eg. cohere.command) Span attribute Dimension
GenAIModelVersion The specific version of the Generative AI model being used Span attribute Dimension
GenAINumGenerations The number of alternative responses generated for the same prompt Span attribute Dimension
GenAIOpcRequestId Unique ID for tracing the request Span attribute Dimension
GenAIPresencePenalty Penalises words after first occurrence, does not factor in frequency of occurrence Span attribute Dimension
GenAIPrompt The final formatted prompt sent to the model, including system instructions, preamble, user input, documents, tool info etc Span attribute Dimension
GenAIPromptLength The total character count of the complete prompt Span attribute Dimension
GenAIQuery The user's input query sent to the Generative AI model Span attribute Dimension
GenAIQueryLength The character count of the user's input query Span attribute Dimension
GenAIResponse The complete response generated by the Generative AI model Span attribute Dimension
GenAIResponseLength The character count of the Generative AI model's response Span attribute Dimension
GenAIResponseTimeCreated The timestamp when the Generative AI response was generated Span attribute Dimension
GenAISearchQueriesOnly If true, only returns relevant search queries, not full answers Span attribute Dimension
GenAISeed Random seed value used for reproducible generation results Span attribute Dimension
GenAIStatusCode HTTP status code returned by the Generative AI Endpoint Span attribute Dimension
GenAIStopSequences List of user specified custom sequences that trigger the model to stop generating text Span attribute Dimension
GenAITemperature Controls randomness in the words selected for the response, lower temperature is more deterministic Span attribute Dimension
GenAITopK Limits the model's token choices to the top K most likely tokens based on their predicted probabilities Span attribute Dimension
GenAITopP The model selects its next token from the set of most likely candidates whose cumulative probability adds up to the top-p threshold Span attribute Dimension
GenAITotalInputLength The total character count of all input sentences or text chunks combined for embedding generation Span attribute Dimension
GenAIUserPreamble Custom instructions or context provided before the main query Span attribute Dimension
HostAddress The IPv4 address resolved from the host name. Trace and span attribute Dimension
Hostname The name of the host. Trace and span attribute Dimension
HostnameCanonical The canonical name (FQDN) of the host. Trace and span attribute Dimension
HostNames The list of host names in the network interfaces of the host. Trace and span attribute Dimension
HttpClientType The type of HTTP client being monitored, for example, Apache HttpClient and HttpURLConnection. Trace and span attribute Dimension
HttpMethod The HTTP method used in the request, for example, GET, POST, and DELETE. Trace and span attribute Dimension
HttpRequestContentSize The content length of the request if Content-Length was set as part of the request header. Trace and span attribute Dimension
HttpResponseContentSize The content length of the response if Content-Length was set as part of the response header. Trace and span attribute Dimension
HttpStatusCode The HTTP status code of the response, for example, 200, 404, or 500. Trace and span attribute Dimension
HttpStatusDetails The description of the HTTP response status code. Trace and span attribute Dimension
HttpUrl The HTTP URL related to the span. Trace and span attribute Dimension
HttpUrlFragment The HTTP URL fragment related to the span. Trace and span attribute Dimension
HttpUrlHost The HTTP URL host name related to the span. Trace and span attribute Dimension
HttpUrlPath The HTTP URL path related to the span. Trace and span attribute Dimension
HttpUrlQuery The HTTP URL query related to the span. Trace and span attribute Dimension
Kind The field related to open tracing definition (https://opentracing.io/specification/conventions/) span.kind0. The Browser agent may report values such as CLIENT or INTERNAL, and the Java agent and other tracers may report values such as SERVER for servlets and CLIENT for HttpClient and JDBC. Trace and span attribute Dimension
NonSampledCount The number of prior non-sampled root spans having the same operation name. Trace and span attribute Metric
OciAvailabilityDomain The Oracle Cloud Infrastructure availability domain the compute instance is running in. Trace and span attribute Dimension
OciCompartmentId The OCID of the compartment in which the compute instance resides. Trace and span attribute Dimension
NonSampledCount The number of prior non-sampled root spans having the same operation name. Trace and span attribute Metric
OciAvailabilityDomain The Oracle Cloud Infrastructure availability domain the compute instance is running in. Trace and span attribute Dimension
OciComputeShape The shape of the compute instance. Trace and span attribute Dimension
OciDisplayName The display name of the compute instance or Kubernetes node. Trace and span attribute Dimension
OciFaultDomain The name of the Oracle Cloud Infrastructure fault domain the compute instance is running in. Trace and span attribute Dimension
OciInstanceId The OCID of the compute instance. Trace and span attribute Dimension
OciRegion The Oracle Cloud Infrastructure region that contains the availability domain the compute instance is running in. Trace and span attribute Dimension
OpcRequestIdRequest The opc-request-id header value set as part of the request sent to the Oracle Cloud Infrastructure. Trace and span attribute Dimension
OpcRequestIdResponse The opc-request-id header value set as part of the response sent from the Oracle Cloud Infrastructure. Trace and span attribute Dimension
OperationName The name of the span. Trace and span attribute Dimension
OsAvailableProcessors The number of processors available to the Java Virtual Machine (JVM). Trace and span attribute Metric
OsFamily The Operating System family derived from the user agent. For example, Linux. Trace and span attribute Dimension
OsName The name of the Operating System. Trace and span attribute Dimension
OsVersion The version of the Operating System. Trace and span attribute Dimension
ProcessId The process ID of the application server. Trace and span attribute Metric
RequestPayload The request payload body captured as part of the request. The request payload may be filtered out to display only useful information using a combination of xpath, jsonpath or regex. For more details, check ProbeConfig.acml file. Trace and span attribute Dimension
ResponsePayload The response payload body captured as part of the response. The response payload may be filtered out to display only useful information using a combination of xpath, jsonpath or regex. For more details, check ProbeConfig.acml file. Trace and span attribute Dimension
ServletContainerSpecification The version of the Servlet specification that the application represented by this ServletContext is based on.

Trace and span attribute Dimension
ServletSpecification The version of the Servlet API that this servlet container supports. Trace and span attribute Dimension
ServiceInstanceId The observer ID of the agent. Trace and span attribute Dimension
ServiceName The name you've assigned to the service. Trace and span attribute Dimension
SessionId The unique identifier of the session or browser. Trace and span attribute Dimension
SoaTaskAssigneeUsers List of Usernames of users to whom this task was assigned.

To see this dimension, you need to set capture_username=true in ProbeConfig.acml file.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskCompletionDuration The time in miliseconds from when the task is initiated to when it is completed.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskName The name of the Task.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskNumber The task number seen in the Number column of the BPM Worklist.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskOutcome The outcome of the task when completed.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskRequester The username of the task's requester.

To see this dimension, you need to set capture_username=true in ProbeConfig.acml file.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskState The state of the task.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaTaskSubstate The substate of the task if available.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SoaWorkflowNumber The workflow number.

This attribute is present when using Oracle SOA Human Workflow.

 Span attribute Dimension
SpanID The unique identifier for each span. Span attribute Dimension
StartTime The start time of the span. Span attribute Metric
Subcomponent The subcomponent that generated the span. Span Attribute Dimension
ThreadAllocatedMemory The approximation of the total amount of memory in bytes allocated in heap memory for the associated Servlet span. This information is obtained from the ThreadMXBean and captured by default.

The default behavior can be disabled using ProbeConfig.acml file from the APM Java Agent. (See tag_thread_allocated_memory parameter.)

Span attribute Dimension
ThreadCpuTime The total CPU time for the associated Servlet span in milliseconds. This information is obtained from the ThreadMXBean and captured by default.

The default behavior can be disabled using ProbeConfig.acml file from the APM Java Agent. (See tag_thread_cpu_time parameter.)

Span attribute Dimension
ThreadId The ID of the thread where the span started. Span attribute Metric
ThreadIdEnd The ID of the thread where the span ended. Span attribute Metric
ThreadName The name of the thread where the span started. Span attribute Dimension
ThreadNameEnd The name of the thread where the span ended. Span attribute Dimension
UserName The user name of the end user using the system, or an identifier that uniquely identifies the user.

For information about username capture and configuration options, see Modify or Disable Default Probe Settings.

Trace and span attribute Dimension
VmName The name of the virtual machine. Trace and span attribute Dimension
VmVendor The vendor of the virtual machine. Trace and span attribute Dimension
VmVersion The version of the virtual machine. Trace and span attribute Dimension
WorkingDirectory The working directory of the application server. Trace and span attribute Dimension