Skip to main content
Version: NG-2.15

vuApp360 Deployment & Configuration

vuSmartMaps Configuration: Enabling Distributed Traces Telemetry​

Traces O11ySource collects Distributed Traces telemetry from applications to provide comprehensive observability, offering deep insights into application performance through standard applications performance monitoring dashboards.

Enabling Traces O11ySource​

  1. Navigate to O11ySources:
    1. vuSmartMaps O11ySources can be accessed by navigating from the left navigation menu (Data Ingestion > O11ySources).
  2. Locate Traces O11ySource on the landing page.

  1. Enable Traces O11ySources:
    1. Click the Enable button to activate Traces O11ySource.

Configuring Data Sources​

  1. Navigate to the Sources tab and click the + button to add new services to be monitored.
  2. Fill up the Following Details in the Wizard:
    1. Applications Group: Name of the application group.
    2. SSL Required: If Yes, TLS will be turned ON.
    3. Application Services: Specify the name of your application and service that will be displayed in the observability UI. In a microservices architecture, an application can consist of multiple services. However, in the absence of microservices, each application would typically have just one service. It is possible to have the same name for both the application and service if desired.
      1. Language: The programming language used for developing the application service: Java, NodeJS, .NET, GoLang.
      2. Application Name: Name of the target application.
      3. Service Name: Service name in the application. Typically in monolithic applications, the service name and application name are the same. In the microservices application, there would be one application that can have one or more services.
    4. Export HTTP Header (True/False): Enable this field, if HTTP Header is required to be captured.

  1. Download the client instrumentation package for the selected language from the agent configuration wizard.

  1. Follow the instructions provided in the client instrumentation package.

Following these steps, you have successfully enabled Traces O11ySource and configured the data sources for real-time application performance monitoring.

Configuring Sampling Policies​

Sampling configuration allows the system to selectively decide on which traces to store. This helps in reducing the amount of data kept in the system.

There are two types of sampling policies that can be configured for traces:

  • Global Policies: Apply to all types of traces coming into the system.
  • Service-Specific Policies: Apply to a specific set of services.

A separate page for sampling-related configurations is introduced. These configurations are controlled from the Settings tab on the Traces O11ySource page. The Settings tab includes three sections:

  1. Sampling Policy
    Defines policies for deciding which traces to store. Policies can use inline rules or refer to rules defined in the Sampling Rules section.
  2. Sampling Rule
    Provides a way to define individual rules that can be referred to in Sampling Policies to form compound rules.
  3. Additional Configuration
    Controls data enrichments and transformations on received traces using optional YAML configurations.

note

The dashboards provided in vuApp360 are designed to display pre-sampled data.

Sampling Policy​

Sampling Policies configured here allow vuSmartMaps to intelligently decide on which traces to store, helping to reduce the amount of data kept in the system by selecting only important traces. This is an optional functionality. If no sampling policies are configured, vuSmartMaps will store 100% of the traces collected.

Sampling policies can use rules defined inline within them or refer to rules defined in the Sampling Rules section. Using rules from sampling rules in policies enables users to define compound policies that can refer to more than one rule. When multiple sampling policies are configured, vuSmartMaps will apply all the policies to all traces received and will take a final decision based on the following:

  • The trace is dropped when there is one explicit 'Do not sample' decision based on an inverted match.
  • The trace is stored when there is one 'Sample' decision.
  • The trace is stored when there is one 'Sample' decision based on an inverted match and there are no 'Do not sample' decisions.
  • The trace is dropped in all other cases.

To configure a new sampling policy, use the + button and provide the following details in the modal:

  • Policy Name: Unique name assigned by the user.
  • Scope: Specify whether the policy applies to all traces (Global) or to a specific set of services. Options include All, For These Services, For Services Except These.
  • Definition Type: Choose to define the policy details inline or refer to a rule defined in the Sampling Rules Section.
    • Inline: If this option is selected, the configured policy type becomes applicable:
  • Policy Type: Specify the type of sampling policy. vuSmartMaps offers following seven policy types:
    1. Allow All: Marks all traces received to be stored.
    2. Data Rate: Tracks spans per second rate of traces and drops traces beyond the configured threshold.
      1. Spans per Second: Maximum number of spans that can be processed each second.
    3. Latency: Stores only those traces with latency greater than the configured threshold.
      1. Threshold in Milliseconds: Only traces with latency greater than the given threshold (in ms) will be allowed.
    4. Number Attribute: Stores only those traces with the value of the configured attribute falling within a specified range.
      1. Attribute: Select the attribute key to match data received from applications (e.g., HTTP Status Code).
      2. Minimum Value: Enter the minimum acceptable value (e.g., 400 for HTTP Status codes).
      3. Maximum Value: Enter the maximum acceptable value (e.g., 500 for HTTP Status codes).
    5. Percentage: Stores only a specified percentage of traces received, dropping the rest.
      1. Sampling Percentage: The percentage rate at which traces are sampled.
    6. Status: Stores traces with specified statuses, dropping the rest.
      1. Status Type: Status value for which traces will be retained. Options: Error, OK, Unset.
    7. String Attribute: Stores only those traces with the value of a configured attribute matching the configured condition.
      1. Attribute: Select the attribute key to match data received from applications (e.g., Application, Service Name, Host Name, HTTP Host, HTTP Target, HTTP Route, HTTP URL, DB Name, DB System, Messaging System, Transaction).
      2. Values: Enter the values to match against (e.g., health, metrics, etc.).
      3. Regular Expression: When 'True', the system will match the attribute values by regular expression string.
      4. Invert Match: When 'True', the system will reverse the match condition.
  • Use Predefined Rule Sets: If this option is selected, choose one of the following policy types and select the relevant rules from the Sampling Rules section:
    1. AND of Multiple Rules: Build a compound rule with an AND of multiple rules defined in the Sampling Rules section.
    2. Rate Distribution: Allocate portions of the total allowed rate to a set of rules from the Sampling Rules Section. Traces matching each rule will be allocated a portion of the total rate allowed.
    3. Single Rule: Use a single rule defined in the Sampling Rules section.

Sampling Rule​

Sampling rules provide a way to define individual rules that can be referred to in Sampling Policies to form compound rules. The rules defined in Sampling Rules are not used unless referred to by a policy in Sampling Policies. Using rules from Sampling Rules in policies enables users to define compound policies that can refer to more than one rule.

To configure a new sampling rule, use the + button and provide the following details in the modal:

  • Rule Name: Unique name assigned by the user.
  • Rule Type: Specify the type of sampling rule. vuSmartMaps offers seven predefined rule types (as explained above for inline policy types).

Additional Configuration​

The Additional Configuration section can be used to control data enrichments and transformations done on traces received. Users can add optional YAML configurations. Below is an example:

transform:  
trace_statements:  
 - context: span  
   statements:  
     - set(attributes["instrumentation_library_name"], instrumentation_scope.name)  
     - set(attributes["library"], attributes["db.system"])  
     - set(attributes["library"], attributes["messaging.system"])  
     - set(attributes["library"], "Express") where instrumentation_scope.name == "@opentelemetry/instrumentation-express"  
     - set(attributes["library"], "MongoDB") where instrumentation_scope.name == "io.opentelemetry.mongo-3.1"  
     - set(attributes["library"], "Go-kit") where instrumentation_scope.name == "go.opentelemetry.io/contrib/instrumentation/github.com/go-kit/kit/otelkit"  
     - set(attributes["library"], "RabbitMQ") where instrumentation_scope.name == "io.opentelemetry.rabbitmq-2.7"  
     - set(attributes["library"], "NodeJS HTTP Client / Server") where instrumentation_scope.name == "@opentelemetry/instrumentation-http"  
     - set(attributes["library"], "Redis") where instrumentation_scope.name == "@opentelemetry/instrumentation-redis"  
     - set(attributes["library"], "Spring MVC") where instrumentation_scope.name == "io.opentelemetry.spring-webmvc-3.1"  
     - set(attributes["library"], "Tomcat") where instrumentation_scope.name == "io.opentelemetry.tomcat-7.0"  
     - set(attributes["library"], "Servlet") where instrumentation_scope.name == "io.opentelemetry.servlet-3.0"  
     - set(attributes["library"], attributes["db.system"]) where instrumentation_scope.name == "io.opentelemetry.jdbc"  
     - set(attributes["library"], "Spring Data") where instrumentation_scope.name == "io.opentelemetry.spring-data-1.8"  
     - set(attributes["library"], "Hibernate") where instrumentation_scope.name == "io.opentelemetry.hibernate-4.0"  
     - set(attributes["library"], "Go HTTP Client / Server") where instrumentation_scope.name == "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"  
     - set(attributes["library"], "Spring Scheduling") where instrumentation_scope.name == "io.opentelemetry.spring-scheduling-3.1 1.14.0-alpha"  
     - set(attributes["destination"], attributes["db.system"])  
     - set(attributes["destination"], attributes["messaging.system"])  
     - set(attributes["destination"], attributes["net.peer.name"])  
     - set(attributes["destination"], replace_match(attributes["http.url"], "https?://[^/]+/([^/]+)", "$1"))  
     - set(attributes["transaction"], Concat([attributes["http.method"], attributes["http.target"]], " ")) where (attributes["http.target"] != nil and attributes["http.method"] != nil and attributes["http.target"] != "")  
     - set(attributes["transaction"], Concat([attributes["http.method"], attributes["http.route"]], " ")) where (attributes["http.route"] != nil and attributes["http.method"] != nil and attributes["http.route"] != "")  
     - set(attributes["site"], "default")

This configuration enriches and transforms trace data, making it more meaningful and useful for analysis.

The Settings tab for Traces O11ySource provides a centralized location for configuring sampling policies, rules, and additional configurations. This setup simplifies the process, reduces user confusion, and enhances the ability to manage and control the data stored in the system effectively. By intelligently sampling traces, users can ensure that they are storing only the most relevant and important data, optimizing both storage and analysis capabilities.

Client Side Traces Instrumentation​

Instrumentation Process

SpringBoot / jar

Steps to instrument the java application running as a SpringBoot / jar:

  1. Download the client instrumentation package from the O11ysource, which contains the vunet-opentelemetry-javaagent.jar.

    1. Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Launch the application with the following configuration

    java -javaagent:path/to/vunet-opentelemetry-javaagent.jar
    -Dotel.resource.attributes=application=<APPLICATION_NAME>
    -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none
    -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT> -jar app.jar

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name.
    • SERVICE_NAME: Change it to match the service name (microservices) or application layer (monolithic)
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps.
      • This should be http://<vuSmartMaps Server IP>:4317.

Example:

  • Here, the vuSmartMaps is running in the host with IP 10.0.0.1 
    java -javaagent:vunet-opentelemetry-javaagent.jar
    -Dotel.resource.attributes=application=UPI -Dotel.service.name=upi-switch
    -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://10.0.0.1:4317 -jar upi.jar

JBoss / WildFly (Standalone Mode) in Linux

Steps to instrument the java application running in JBoss / WildFly (Standalone Mode) in Linux:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit the <JBOss_HOME>/bin/standalone.conf file and update the JAVA_OPTS environment variable

    JAVA_OPTS="-javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT>"

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single JBoss / Wildfly server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

    Example:

    JAVA_OPTS="$JAVA_OPTS -javaagent:D:\Dev\OTel\auto_instrumentation_package_java\otel-lib\vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=APPLICATION_NAME -Dotel.service.name=SERVICE_NAME -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://localhost:4317"

  4. Restart JBoss

JBoss / WildFly (Domain Mode) in Linux

Steps to instrument the java application running in JBoss / WildFly (Domain Mode) in Linux:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit the <JBOss_HOME>/bin/domain.conf file and update the JAVA_OPTS environment variable

    JAVA_OPTS="-javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT>"

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single JBoss / Wildfly server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317.

    Example:

    JAVA_OPTS="$JAVA_OPTS -javaagent:D:\Dev\OTel\auto_instrumentation_package_java\otel-lib\vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=APPLICATION_NAME -Dotel.service.name=SERVICE_NAME -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://localhost:4317"

  4. Restart JBoss

JBoss / WildFly (Standalone Mode) in Windows

Steps to instrument the java application running in JBoss / WildFly (Standalone Mode) in Windows:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit the <JBOss_HOME>/bin/standalone.conf.bat file and update the JAVA_OPTS environment variable

    JAVA_OPTS="-javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT>"

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single JBoss / Wildfly server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317.

    Example:

    set "JAVA_OPTS=%$JAVA_OPTS% -javaagent:D:\Dev\OTel\auto_instrumentation_package_java\otel-lib\vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=APPLICATION_NAME -Dotel.service.name=SERVICE_NAME -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://localhost:4317"

  4. Restart JBoss

JBoss / WildFly (Domain Mode) in Windows

Steps to instrument the java application running in JBoss / WildFly (Domain Mode) in Windows:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit the <JBOss_HOME>/bin/domain.conf.bat file and update the JAVA_OPTS environment variable

    JAVA_OPTS="-javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT>"

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single JBoss / Wildfly server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317.

    Example:

    set "JAVA_OPTS=%$JAVA_OPTS% -javaagent:D:\Dev\OTel\auto_instrumentation_package_java\otel-lib\vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=APPLICATION_NAME -Dotel.service.name=SERVICE_NAME -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://localhost:4317"

  4. Restart JBoss

Apache Tomcat running on Linux

Steps to instrument the java application running in Apache Tomcat running on Linux

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit the setenv.sh in the bin directory of Tomcat and add the following content.

    • Create the setenv.sh in the bin directory if it doesn't exist 
      export CATALINA_OPTS="$CATALINA_OPTS -javaagent:path/to/vunet-opentelemetry-javaagent.jar"
      export OTEL_EXPORTER_OTLP_ENDPOINT=<TRACES_INGESTION_ENDPOINT>
      export OTEL_RESOURCE_ATTRIBUTES=application=<APPLICATION_NAME> 
      export OTE_SERVICE_NAME=<SERVICE_NAME>
      export OTEL_METRICS_EXPORTER=none

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single Apache Tomcat server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

  4. Restart Apache Tomcat

Apache Tomcat running on Windows

Steps to instrument the java application running in Apache Tomcat running on Windows:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit the setenv.bat in the bin directory of Tomcat and add the following content.

    • Create the setenv.bat in the bin directory if it doesn't exist 
      set "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:path\to\vunet-opentelemetry-javaagent.jar" 
      set "OTEL_EXPORTER_OTLP_ENDPOINT=<TRACES_INGESTION_ENDPOINT>" 
      set "OTEL_RESOURCE_ATTRIBUTES=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME>" 
      set "OTEL_METRICS_EXPORTER=none"

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single Apache Tomcat server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

  4. Restart Apache Tomcat

Weblogic (Standalone Weblogic Servers)

Steps to instrument the java application running in a standalone Weblogic server:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Edit startWebLogic.sh located at <weblogic_<version#>_install_dir>/user_projects/domains/<domain_name>/bin/startWebLogic.sh.

    • Add the following to the beginning of your application server start script 
      export   JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT>"

  3. Ensure to update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single Weblogic server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

  4. Restart Weblogic

Weblogic (Servers managed by Admin Console)

Steps to instrument the java application running in clustered Weblogic server where the admin console is used to manage the instance:

  1. Download the client instrumentation package, which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. For clustered WebLogic servers, you start and stop using Node Manager and configure server startup in the WebLogic Server Administration Console.

  3. Open the WebLogic Server Administration Console.

  4. Navigate to Environment > Servers and click your server in the Server List

  5. Click the Server Start tab.

  6. Add the javaagent argument and set the value to the path to the Java Agent

    -javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT> -Dotel.exporter.otlp.compression=gzip

  7. Please update the following before using this command.

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single Weblogic server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

  8. Restart the Weblogic managed server

Websphere Application Server ND

Steps to instrument the java application running in Websphere Application Server Network Deployment:

  1. Download the client instrumentation package which contains the vunet-opentelemetry-javaagent.jar.

    • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  2. Log in to the WebSphere Integrated Solutions Console

  3. Navigate to Servers > Server type > WebSphere application servers.

  4. Select the server.

  5. Go to Java and Process Management > Process Definition.

  6. Select Java Virtual Machine.

  7. In Generic JVM arguments, add the following arguments.

    -javaagent:path/to/vunet-opentelemetry-javaagent.jar -Dotel.resource.attributes=application=<APPLICATION_NAME> -Dotel.service.name=<SERVICE_NAME> -Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=<TRACES_INGESTION_ENDPOINT> -Dotel.exporter.otlp.compression=gzip

  8. Please update the following before saving the configuration

    • APPLICATION_NAME: Change it to match your application name
    • SERVICE_NAME:
      • Change it to match the service name (microservices) or application layer (monolithic).
      • When multiple war files are running in a single Weblogic server, then enable the auto discovery of service name using the argument 
        -Dotel.service.name=FROM_WEB_CONTEXT
    • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

  9. Save the configuration and restart the server.

Docker

If your application is running in Docker, then modify the Dockerfile to include the JVM parameters mentioned above.

See the extract from a sample Dockerfile.

COPY ./vunet-opentelemetry-javaagent.jar /usr/local/lib/vunet-opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS "-javaagent:/usr/local/lib/vunet-opentelemetry-javaagent.jar"
ENV OTEL_RESOURCE_ATTRIBUTES "application=<Application Name>"
ENV OTEL_SERVICE_NAME "<Service Name>"
ENV OTEL_EXPORTER_OTLP_ENDPOINT "<TRACES_INGESTION_ENDPOINT>"
ENV OTEL_METRICS_EXPORTER "none"
ENTRYPOINT ["java","-Djava.security.egd=file:/dev/urandom","-jar","./app.jar", "--port=80"]

If you don’t want to rebuild the container, then you can re-run the container with the following additional environment variables.

docker run -d \
-v ./vunet-opentelemetry-javaagent.jar:/app/opentelemetry-javaagent.jar \
-e OTEL_EXPORTER_OTLP_ENDPOINT=<TRACES_INGESTION_ENDPOINT>\
-e OTEL_SERVICE_NAME=<Service Name> \
--entrypoint java \
-javaagent:/usr/local/lib/vunet-opentelemetry-javaagent.jar \
-jar /app/myapp.jar

Ensure to update the following before using this command.

  • APPLICATION_NAME: Change it to match your application name
  • SERVICE_NAME: Change it to match the service name (microservices) or application layer (monolithic)
  • TRACES_INGESTION_ENDPOINT: Change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317

Configuration

TLS Configuration

If the TLS is enabled on the vuSmartMaps traces receiver, please get the certificate from the server and configure the following additional parameters.

-Dotel.exporter.otlp.protocol=http/protobuf
-Dotel.exporter.otlp.certificate='/path/to/server/certificate'
note

The server certificate is included in the downloaded instrumentation package.

For the TLS case TRACES_INGESTION_ENDPOINT should be https://<vuSmartMaps Server IP>:4318

Capture HTTP Headers

In some applications, key transaction identifiers are passed as HTTP headers to the APIs. To capture these headers, additional instrumentation configurations are required. Below are the steps and examples for capturing HTTP headers for both HTTP servers and clients.

Capture HTTP Request Header for HTTP Server

To capture the request headers passed to a service, use the following configuration along with other instrumentation configurations mentioned in the previous sections.

OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS

You can configure one or more headers to be captured. If capturing multiple headers, separate them with commas.

An example is given below

java -javaagent:vunet-opentelemetry-javaagent.jar
-Dotel.resource.attributes=application=UPI -Dotel.service.name=upi-switch
-Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://10.0.0.1:4317 -jar 
-Dotel.instrumentation.http.server.capture-request-headers=client_id,txn_id
upi.jar

Capture HTTP Response Header for HTTP Server

To capture the response headers passed from a service, use the following configuration along with other instrumentation configurations mentioned in the previous sections.

OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS

You can configure one or more headers to be captured. If capturing multiple headers, separate them with commas.

An example is given below

java -javaagent:vunet-opentelemetry-javaagent.jar
-Dotel.resource.attributes=application=UPI -Dotel.service.name=upi-switch
-Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://10.0.0.1:4317 -jar 
-Dotel.instrumentation.http.server.capture-response-headers=resp_code,resp_status
upi.jar

Capture HTTP Request Header for HTTP Client

To capture the request headers passed by a service, use the following configuration along with other instrumentation configurations mentioned in the previous sections.

OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS

You can configure one or more headers to be captured. If capturing multiple headers, separate them with commas.

An example is given below

java -javaagent:vunet-opentelemetry-javaagent.jar
-Dotel.resource.attributes=application=UPI -Dotel.service.name=upi-switch
-Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://10.0.0.1:4317 -jar 
-Dotel.instrumentation.http.client.capture-request-headers=client_id,txn_id
upi.jar

Capture HTTP Response Header for HTTP Client

To capture the response headers received by a service, use the following configuration along with other instrumentation configurations mentioned in the previous sections

OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS

You can configure one or more headers to be captured. If capturing multiple headers, separate them with commas.

An example is given below

java -javaagent:vunet-opentelemetry-javaagent.jar
-Dotel.resource.attributes=application=UPI -Dotel.service.name=upi-switch
-Dotel.metrics.exporter=none -Dotel.exporter.otlp.endpoint=http://10.0.0.1:4317 -jar 
-Dotel.instrumentation.http.client.capture-response-headers=resp_code,resp_status
upi.jar