Troubleshooting .NET tracing on Linux or Alpine Linux

Symptoms: Application shows metrics but no traces, some services report, but others don't, or tracing stops after a deployment or update.

Troubleshooting steps:

1. Verify that the .NET version of the application is supported:

   • .NET Core Runtime 5.0 or later
2. Verify that tracing is enabled in the agent configuration.yaml file.
3. Collect trace logs by using Log Collector or by collecting logs manually.

4. Check the Instana tracing logs:

   • If the logs are empty or no traces are visible, the application is not producing spans.
   • If traces are present in the logs but are missing information (for example, host), the problem is with the .NET tracing layer.
   • If traces are present in the logs and contain information that is missing in the UI, the problem occurred either in the Instana backend or the agent.

Symptom: The application fails on startup when the Instana agent is running.

Troubleshooting steps:

1. Verify that the .NET Core version of the application is supported:

   • .NET Core Runtime 5.0 or later
2. Collect logs by using Log Collector or by collecting logs manually.
3. Collect crash dump for the application.

Symptom: The .NET application is not being monitored by the Instana agent and is not present in the UI.

Troubleshooting steps:

1. Collect Instana agent logs by using Log Collector or by collecting logs manually.
2. Verify that the Instana agent is run as administrator.
3. Verify that the Instana agent has permissions to monitor the application.

4. Verify that sensors are successfully activated in the agent logs.

   com.instana.sensor-clr - <version> |  | Activated Sensor

5. Verify that the .NET process is started after the Instana agent.

Symptom: The .NET application shows unusually high CPU usage after tracing is enabled.

Troubleshooting steps:

1. Identify the source: Determine whether the issue is related to the application by checking the system monitor.

2. If an application memory spike is present:

   • Check /var/log and .NET logs for memory-related exceptions.
   • Verify whether the issue is caused by Instana instrumentation.
   • Request a .NET dump file for further analysis.

Log Collector is a stand-alone application to collect logs from Instana. You can trigger the Log Collector from the following locations:

• Instana UI
• Console

The Log Collector collects the following logs:

• Application tracing logs
• CLR debug logs
• Instana agent debug logs
• Instana agent traces logs

Alternatively, you can collect logs manually without using the log collector. Complete the following steps:

1. Enable debug logs: Set the following environment variables manually at the system level and restart the application:

   export INSTANA_NET_LOG_PATH="<Log_path>"
   export INSTANA_NET_LOG_LEVEL=DEBUG
   export INSTANA_NET_CORE_LOG_LEVEL=DEBUG
   export INSTANA_TRACER_ENTEREXIT_LOGGING=1
   export INSTANA_EXTENDED_DEBUG=1
   export INSTANA_CLRLOG_PATH=/var/tmp/clr_

2. Collect Instana agent logs:

   1. Stop the agent:

      sudo systemctl stop instana-agent.service

   2. Wipe the logs: Delete all files in the logs directory to start fresh:

      sudo rm -rf <instana_install_dir>/data/logs/*

   3. Set the log level to debug: Change the log level severity in the configuration file:

      Update log level in <instanaAgentDir>/etc/org.ops4j.pax.logging.cfg configuration file from log4j2.logger.instana.level=INFO to log4j2.logger.instana.level=DEBUG.

      Important: Ensure that the line has no trailing white space.

   4. Start the agent:

      sudo systemctl start instana-agent.service

   5. Check logs in the log folder and collect the logs: Compress the logs directory for submission:

      cd <instana_install_dir>/data/logs/
      zip -r instana_agent_debug_logs.zip *