Skip to main content
Version: NG 3.0 (Beta)

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 (Integrations > O11ySources).

  2. Locate Traces O11ySource on the landing page.

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

Nice! You're just a few steps away from enabling code-level observability. Let’s get this instrumented!

Configuring Data Sources​

To add and configure a Traces data source:

  1. Go to the Sources tab inside the Traces O11ySource. Click Source (top-right) → Configure New.

  1. This opens the Configure New Data Source(s) wizard, which includes:

Step 1: Add Data Source​

In this step, you provide the basic details required for configuring Traces.

Fill in the following fields:

  • Application Group: Enter the name of the application group to which this service belongs.
  • SSL Required: Select Yes to enable TLS for secure communication, or No if TLS is not required.
  • Attributes to be used as Additional Dimensions (Optional): Specify trace attributes that should be used as additional dimensions while calculating metrics.
    • Separate multiple attributes using commas (for example: attribute1, attribute2).
    • For HTTP request headers, use the format: http.request.header.<attribute_name>
    • For HTTP response headers, use the format: http.response.header.<attribute_name>
    • For other attributes, use the exact field name as available in the raw trace data.
  • Enable Tail Sampling: Select Yes to apply the tail sampling policies configured in the Settings tab to determine which traces are stored. Select No to store 100% of the collected traces.
  • Application Services: Define the application and service names as they should appear in the observability UI.
    • In a monolithic application, the application name and service name are usually the same.
    • In a microservices architecture, a single application can include multiple services.
  • Language: Select the programming language used to develop the service (Java, NodeJS, .NET, or GoLang).
  • Application Name: Enter the name of the target application.
  • Service Name: Enter the name of the service within the application.
  • Export HTTP Header: Enable this option if HTTP headers need to be captured as part of trace data.

After entering the required details, click Proceed.

Step 2: Configuration Setup​

In this step, you define how the Traces data source will be managed by the platform. The table displays the configured source with the following details:

  • Host IP – The host or application identifier added in the previous step.
  • Dataset – Automatically set to Traces.
  • Managed by – Specifies how trace data will be collected for the source. Only management modes supported for Traces are displayed.

Management Modes

  • OmniAgent Managed: Tracing is handled automatically by OmniAgent. Once the OmniAgent is discovered on the host, trace collection starts automatically. Until discovery, the source remains in a Pending state.
  • Manually Managed: Tracing is managed manually using client-side instrumentation.
    • Download the required instrumentation package for the selected programming language, refer Download Source section.
    • Deploy and configure the instrumentation manually on the application host.
    • Trace data collection starts once the instrumentation is integrated and the application is running.
  • Remote Collection: Trace data is collected remotely without installing OmniAgent on the host, where supported. Data collection proceeds automatically once the configuration is applied.

After selecting the appropriate Managed by option, click Proceed to continue to the Review step.

Step 3: Review​

The Review step displays the configured Traces data sources and provides guidance on how data collection will proceed based on the selected management mode.

In this view, you can:

  • Review the host, dataset, and management mode for each configured source.
  • Filter sources using the Managed by options (OmniAgent, Manual, Remote).
  • Search for specific configurations using the search bar.

Based on the selected management mode:

  • Manually Managed – Download the required client instrumentation packages from the configured Sources table and deploy them manually.
  • Remote Collection – Data collection proceeds automatically without requiring agent installation.
  • OmniAgent Managed – Data collection proceeds automatically once OmniAgent is discovered. Until then, the source remains in a Pending state. The OmniAgent package can be downloaded if required.

After reviewing the configuration, click Finish to complete the setup. The Traces data source will then be available in the Sources list and begin collecting data according to the selected configuration.

Download Source​

If the data source uses Manually Managed mode, you must download the client instrumentation package. To download:

  1. Go to the Sources table.
  2. Click the Download icon in the Actions column.
  3. Select the required configuration for the chosen language.
  4. Click Submit.

This provides the client instrumentation package required for trace collection. Follow the instructions provided in the Client Side Traces Instrumentation section to complete the setup.

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​

A wide range of languages are supported—pick what suits your app best, instrument it, and you’re all set for observability magic!

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

Follow the below instructions to instrument the Java application running in Apache Tomcat:

  • Download the client instrumentation package which contains the vunet-opentelemetry-javaagent.jar.
  • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.
  • Edit the setenv.bat file located in the bin directory of Tomcat.
  • If it doesn’t exist, create a new one in the same directory.

Add the following content:

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"

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 (for microservices) or application layer (for monolithic applications).
  • TRACES_INGESTION_ENDPOINT – Change it to match the URL of vuSmartMaps.
    It should be in the format:
http://<vuSmartMaps Server IP>:4317
  • Restart Apache Tomcat after completing the above configuration.

Apache Tomcat Running as Windows Service

Follow the below instructions to instrument the Java application running in Apache Tomcat which is running as a Windows Service:

  • Download the client instrumentation package which contains the vunet-opentelemetry-javaagent.jar.
  • Place the vunet-opentelemetry-javaagent.jar in your preferred directory.
  • Open the Tomcat Service Configuration
    • Open the command prompt in Administrator mode
    • Navigate to the bin folder of Tomcat
    • Run the below command
tomcat9w.exe //ES//<SERVICE_NAME>
  • Replace <SERVICE_NAME> with the actual internal service name
  • For example:
tomcat9w.exe //ES//Service_1

  • In the Tomcat Service Configuration, go to the Java tab.

  • In the Java Options box add the following
-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=http://<vuSmartMaps Server IP>:4317

Please update the following before using this command:

  • APPLICATION_NAME – Please change it to match your application name.
  • SERVICE_NAME – Please change it to match the service name (microservices) or application layer (monolithic).
  • TRACES_INGESTION_ENDPOINT – Please change it to match the URL of vuSmartMaps It should be in the format:
http://<vuSmartMaps Server IP>:4317
  • Click Apply and OK to save
  • 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

Websphere Liberty

Follow the below instructions to instrument the java applications running in Websphere Liberty servers

  • Download the client instrumentation package which contains the vunet-opentelemetry-javaagent.jar. Place the vunet-opentelemetry-javaagent.jar in your preferred directory.

  • Locate the liberty server config. Each Liberty server instance has its own directory, like

$WLP_USER_DIR/servers/<server_name>/

Inside it, you will find server.xml, jvm.options etc. If you don't find jvm.options, please create the file.

  • Add the following configurations to the jvm.options file
-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
  • Please update the following before saving the configuration
    • APPLICATION_NAME - Please change it to match your application name
    • SERVICE_NAME - Please Change it to match the service name (microservices) or application layer (monolithic)
    • TRACES_INGESTION_ENDPOINT - Please change it to match the URL of the vuSmartMaps. It should be http://<vuSmartMaps Server IP>:4317
  • Save the file and restart the liberty server using the below commands.
bin/server stop \<server\_name\>

bin/server start \<server\_name\>

  • Repeat this for all the Liberty servers that need to be instrumented.

  • Once this is done, you will see the traces in the vuSmartMaps dashboard

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

Kubernetes

When you run your Java applications in Kubernetes based environments, please follow the kubernetes tab.

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