Configuring host agent

Configuring Instana backend

The Instana host agent connects to the Instana backend by using the HTTP/2 protocol with TLSv1.3 encryption. The connection is always established in a secure and encrypted way. For more information, see Setting up TLS encryption for agent endpoint.

The <instana-agent-dir>/etc/instana/com.instana.agent.main.sender.Backend.cfg file contains the configurations that are used by the host agent to communicate with the Instana backend.

The values of the <instana-agent-dir>/etc/instana/com.instana.agent.main.sender.Backend.cfg file can be overridden by using the following environment variables:

• INSTANA_AGENT_ENDPOINT - The host name of the Instana backend/service that your host agent connects to.
• INSTANA_AGENT_ENDPOINT_PORT - The TCP port that your host agent connects to. The default is 443.
• INSTANA_AGENT_KEY - The agent key used to create a relationship between the host agent and the Instana backend/service.

Values for the Instana agent endpoint and port are reported in the agent log; for example:

2024-04-16T05:09:09.627+0000 | INFO  | ... | Backend | 55 - com.instana.agent - 1.1.718 | Connected using HTTP/2 to ingress-pink-saas.instana.rocks:443 ...

The endpoint, port, and agent key values are shown on Agent deployment screens in the Instana UI; for example, on a Linux - Automatic Installation (One-liner) screen, the deployment code includes ... -a aGeNTKEY0vaLuO0Eu1ABc ... -e ingress-green-saas.instana.io:443.

Setting up an agent proxy

To communicate with the backend effectively, Instana uses the HTTP/2 protocol to transfer the data.

In many cases, direct communication from the host agent to the backend can be granted to simplify the deployment of the agent.

In some cases, one dedicated entry is required that goes in or out of the network. For this reason, use Instana with various proxies. In general, HTTP, HTTPS, SOCKS4, and SOCKS5 proxies are supported. The proxy needs to support the CONNECT method to pass through. TLS termination at the proxy level is supported as long as HTTP/2 with ALPN is supported by the proxy.

For the host agent configuration, modify the following files:

• <instana-agent-dir>/etc/mvn-settings.xml
• <instana-agent-dir>/etc/instana/com.instana.agent.main.sender.Backend.cfg

In the <instana-agent-dir>/etc/mvn-settings.xml file, the following information must be present and not commented out in the <settings></settings> section:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>data/repo</localRepository>
  <servers>
    <server>
      <id>features</id>
      <username>_</username>
      <password>_</password>
    </server>
    <server>
      <id>shared</id>
      <username>_</username>
      <password>_</password>
    </server>
    <!-- for mirrors requiring auth
    <server>
      <id>features-mirror</id>
      <username>myuser</username>
      <password>mypassword</password>
    </server>
    <server>
      <id>shared-mirror</id>
      <username>myuser</username>
      <password>mypassword</password>
    </server>
    -->
  </servers>

  <!-- If you want to access the Instana repository using an HTTP/Socks proxy,
       uncomment the proxies section and insert proxy details. -->
  <!-- https://maven.apache.org/guides/mini/guide-proxies.html -->
  <!--
  <proxies>
    <proxy>
      <id>agent-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <username></username>
      <password></password>
      <host></host>
      <port></port>
    </proxy>
  </proxies>
  -->

  <!-- If you want to use a company internal mirror, make sure that mirror is
       configured to use the Instana repository, uncomment the mirrors section
       and insert maven mirror details.
       If the mirror also requires auth it can be added above. -->
  <!-- https://maven.apache.org/guides/mini/guide-mirror-settings.html -->
  <!-- Repos that need to be mirrored -->
  <!-- feature: https://artifact-public.instana.io/artifactory/features-public -->
  <!-- shared: https://artifact-public.instana.io/artifactory/shared -->
  <!--
  <mirrors>
    <mirror>
      <id>features-mirror</id>
      <url>http://repo.mycompany.com/artifactory/instana-public</url>
      <mirrorOf>features</mirrorOf>
    </mirror>
    <mirror>
      <id>shared-mirror</id>
      <url>http://repo.mycompany.com/artifactory/instana-shared</url>
      <mirrorOf>shared</mirrorOf>
    </mirror>
  </mirrors>
  -->

</settings>

The configuration for the proxies uses the Instana agent in an environment with a proxy to communicate with the Maven endpoint configured in the mvn-settings.xml file.

Furthermore, you need to reconfigure the <instana-agent-dir>/etc/instana/com.instana.agent.main.sender.Backend.cfg configuration file to use the proxy to communicate between the agent and the Instana backend.

Make sure that the following lines are present and not commented out:

proxy.type=http
proxy.host=your-proxy-address-goes-here
proxy.port=your-proxy-port-goes-here
proxy.user=user-if-needed
proxy.password=password-if-needed
proxy.dns=true

# The tcp port squid is listening on
http_port 3128

# Please specify subnet with instana agents
acl instana_agent_net src 10.0.0.0/8

# This is the ip of the instana backend
acl instana_backend dstdomain saas-eu-west-1.instana.io
#acl instana_backend dstdomain ec2-54-144-114-141.compute-1.amazonaws.com
#acl instana_backend dstdomain saas-us-east-1.instana.io
#acl instana_backend dstdomain saas-us-east-1.instana.io

# This is the port used by Instana
acl instana_backend_port port 443

# This is the repo to download updates and additional sensors
acl instana_repo dstdomain artifact-public.instana.io
acl instana_repo_port port 80
acl instana_repo_port_secure port 443

# Protocol used for instana backend
acl instana_backend_proto proto HTTP

# Protocol used for instana backend
acl instana_repo_proto proto HTTP
acl instana_repo_proto_secure proto HTTPS

http_access allow instana_agent_net instana_backend instana_backend_port
http_access allow instana_agent_net instana_repo instana_repo_port
http_access allow instana_agent_net instana_repo instana_repo_port_secure

# DO NOT REMOVE THIS RULE!
http_access deny all

Setting up TLS encryption for agent endpoint

By default, HTTP network connections to the agent on port 42699 and gRPC connections on port 4317 are not encrypted.

You can configure the agent to accept TLS-encrypted requests.

The following TLS versions are enabled: TLSv1, TLSv1.1, TLSv1.2, and TLSv1.3. The available TLS versions also apply when the agent itself issues secure requests, such as when the agent connects to external metrics resources.

You can enable TLS encryption on the agent endpoints on port 42699 and 4317 by adding certificates in the <agent_installation>/etc/certs/ directory. By default, the agent looks for the following files:

• <agent_installation>/etc/certs/tls.crt
• <agent_installation>/etc/certs/tls.key

Other names, such as <agent_installation>/etc/certs/<your_certificate_name>.crt or <agent_installation>/etc/certs/<your_key_name>.key, are also allowed for the .crt and .key files if the <agent_installation>/etc/certs/ directory has only one file of each.

After you add the certificates, restart the agent to initialize the network connections.

Important: The host agent does not allow _enforcing_TLS encryption. TLS is enabled on a connection only on the client's request.

Configuring host agent mode

The One-Liner host agent installation method and the Instana Host Agent Docker image accept an extra mode that is the AWS mode.

The AWS mode of the host agent is not used for monitoring hosts. The INFRASTRUCTURE mode plus some automatic configuration of AWS data collection, as described in the AWS Agent documentation is used for monitoring hosts.

You can set the host agent mode by configuring the <instana-agent-dir>/etc/instana/com.instana.agent.main.config.Agent.cfg configuration file:

mode = APM
# APM, INFRASTRUCTURE or OFF

After you change the <instana-agent-dir>/etc/instana/com.instana.agent.main.config.Agent.cfg configuration file, you must restart the host agent for the changes to take effect.

mode.web-override.allowed = false

Configuring host agents by using the agent configuration file

Most host agent configurations are applied by using the agent configuration file (<instana-agent-dir>/etc/instana/configuration.yaml).

By using the agent configuration file, you can achieve the following goals:

• Create multiple configuration files
• Integrate the host agent with secret managers
• Obtain configurations from process environment and files
• Monitor extra file systems
• Specifying host tags
• Extract the installed packages list
• Set custom zones
• Monitor custom processes
• Configure secrets
• Capture custom HTTP headers
• Configure Kafka trace correlation headers
• Ignore processes
• Deactivate agent capabilities triggered by Instana UI
• Upload code source files to Instana
• Configure error report events (only AIX operating system)

For more information, see the Configuring host agents by using the agent configuration file topic.

Agent logging

By default, the Instana agent logs to the <instana-agent-dir>/data/log/agent.log log file, which is rotated if the file grows too large. If you are running the agent in a container, the Instana agent logs to the console instead, which is managed by the Docker and is accessible by using the Docker logs.

The log level can be increased to debug by changing the level in the <instana-agent-dir>/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.

The older agent installs need this line to be changed from log4j.logger.com.instana=INFO, out, osgi:* to log4j.logger.com.instana=DEBUG, out, osgi:*

log4j2.appender.rolling.policy.type = SizeBasedTriggeringPolicy
log4j2.appender.rolling.policy.size = 5MB
log4j2.appender.rolling.strategy.type = DefaultRolloverStrategy
log4j2.appender.rolling.strategy.max = 10

log4j2.rootLogger.appenderRef.Syslog.ref = Syslog
log4j2.rootLogger.appenderRef.Syslog.level = ERROR
log4j2.appender.syslog.type=Syslog
log4j2.appender.syslog.name=Syslog
log4j2.appender.syslog.layout.type=PatternLayout
log4j2.appender.syslog.layout.pattern = ${log4j2.pattern}
log4j2.appender.syslog.facility=SYSLOG
log4j2.appender.syslog.host=localhost
log4j2.appender.syslog.port=514
log4j2.appender.syslog.protocol=UDP

log4j2.rootLogger.appenderRef.Console.ref = Console

log4j2.appender.console.type = Console
log4j2.appender.console.name = Console
log4j2.appender.console.layout.type = PatternLayout
log4j2.appender.console.layout.pattern = ${log4j2.pattern}

# Configuration of local logging. Changes will be hot-reloaded.
# Activate logging of outgoing payloads to local disk by setting a non-empty
# prefix. The log file will be written to data/log, and the file will have the
# defined prefix followed by a timestamp.
# Note: There is no automatic rotation of those files.
prefix=locallog

# The file can be filtered to either "metrics" or "traces".
# If empty or absent, there will be no filtering.
type=traces

Limiting host agent CPU and memory

In certain scenarios, controlling resource consumption of processes closely is crucial. This controlling can become especially helpful in environments that use resource sharing, and for the systems with low resources. While the Instana agent is designed to use few resources as possible, the resources can be further limited by following these instructions as another safeguard to respect clear resource limits.

All the following examples limit the agent's CPU to computing resources equivalent to half a CPU and to a maximum of 512 MB memory. However, not all resources would necessarily come from the same CPU.

[Service]
CPUAccounting=true
CPUQuota=50%
MemoryAccounting=true
MemoryMax=512M

Run the `instana-agent` container with the following extra parameters:

--cpus=0.5 --memory=512m

--cpu-period=100000 --cpu-quota=50000 --memory=512m

livenessProbe:
  httpGet: # Agent liveness is published on localhost:42699/status
    path: /status
    port: 42699
  initialDelaySeconds: 75
  periodSeconds: 5
resources:
  requests:
    memory: "256Mi"
    cpu: "0.5"
  limits:
    memory: "512Mi"
    cpu: "1.0"

Converting a static agent to a dynamic agent

To change a static agent to a dynamic agent, update the following configuration files:

• Update the <agent-dir>/etc/org.ops4j.pax.url.mvn.cfg file as shown:

  org.ops4j.pax.url.mvn.repositories=https://artifact-public.instana.io/artifactory/features-public@id=features@snapshots@snapshotsUpdate=always,https://artifact-public.instana.io/artifactory/shared@id=shared@snapshots@snapshotsUpdate=always
  

• Update the <agent-dir>/etc/instana/com.instana.agent.main.config.UpdateManager.cfg file as shown:

  mode=AUTO
  

• In <agent-dir>/etc/instana/com.instana.agent.bootstrap.AgentBootstrap.cfg file, ignore or remove the version or pin based on your requirements as shown:

  #version=<hash>
  

• Delete all the references to the version of the BOMs present in the system directory by executing the following command:

  find <agent-dir>/system/ -type d -name '1.0.0-SNAPSHOT' -exec rm -rv {} \;
  

Attention: If you install a dynamic agent first, you cannot change it to a static agent.