IBM Support

MustGather: Instana Java Sensor/Tracer/Profiler

Troubleshooting


Problem

This guide provides essential steps for collecting data related to Instana Java Sensor/Tracer/Profiler. Before contacting IBM® support for assistance, please review the information below to familiarize yourself with the troubleshooting process.

Resolving The Problem

To explore potential solutions, search for issues, access documentation, or visit support forums, head to the IBM® Support page. If you are aware of the affected component, refer to the relevant MustGather details below:
 
MustGather Data Collection Requirements for Instana Java Sensor/Tracer/Profiler

Monitored environment details:
 
  • Kind of deployment (Single host , Kubernetes, Docker, podman, AWS Fargate, Azure or Google cloud)
  • OS (Linux/ Windows) and version
  • SaaS url of the agent monitoring the Java application
  • Java variant and its precise version used
  • A detailed list of libraries used in the application, including their exact versions
  • Application flow if Instana is Self hosted or On-prem.
  • Process ID where issue is seen.
 
Agent logs:
 
  • Collect debug log of Instana agent:
    • See the MustGather page for Instana Agent for more details
 
Agent configuration:
 
  • Collect <instana-agent-dir>/etc/instana/configuration.yaml file 
 
Additional output & files to collect (if this is a tracer issue):
 
  • Enable and capture the trace log:
    • Add the following configuration (in a non-production environment) in the <instana-agent-dir>/etc/instana/configuration.yaml file: 
      • com.instana.plugin.javatrace:
  instrumentation:
    log:
      type: trace
      file: /tmp/trace.log
    • If this is a Production environment, and a "minimal" span trace log is preferred (generates less trace entries), add the following configuration in the <instana-agent-dir>/etc/instana/configuration.yaml file:
      • com.instana.plugin.javatrace:
  instrumentation:
    log:
      type: minimal
      file: /tmp/trace.log
    • In a kubernetes environment, the agent configuration change needs to be made in the "agents.instana.io" custom resource definition (CRD).
      • It would be necessary to restart the agent pod in the appropriate cluster node (the cluster node where the service to be traced is running) in order for the configuration change to take effect.
      • The trace log will be created in the pod in which the service is running and not the Instana agent pod.
      • Once tracing is complete, the agent pod would need to be restarted again after the trace parameters have been removed from the CRD
    • NOTE: The trace log file will be generated by the application and not the agent, so the file defined by the file setting must be writable by it.
  • If issue is related to missing calls or mis-correlated calls then share the expected calls. For example, if spans are missing related to a DB transaction, then please list the details of these spans that are missing
  • If issue is related to the Profiler, and if heap dump generation is enabled ("ulimit -c unlimited"), please upload the heap dump and related files:
    • .crash file under /var/crash (or other location depending on the system)
    • hs_err_pid<pid>.log (under the application's default current directory)

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSE1JP5","label":"IBM Instana Observability"},"ARM Category":[{"code":"a8mgJ00000005VxQAI","label":"Tracers"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"1.0.281;1.0.282;1.0.283;1.0.284;1.0.285;1.0.286;1.0.287;1.0.288;1.0.289;1.0.290;1.0.291;1.0.292;1.0.293;1.0.294;1.0.295;1.0.296;1.0.297;1.0.298;1.0.299;1.0.300;1.0.301;1.0.302;1.0.303;1.0.304;1.0.305;1.0.306;1.0.307"}]

Document Information

Modified date:
10 November 2025

UID

ibm17247165

Page Feedback