<\/p>\n\n\n\n
https:\/\/<hash>.apm.<region>.cloud.es.io:443<\/code>)<\/li>\n\n\n\n- Secret token<\/strong> or<\/em> an APM Agent key (API key)<\/strong>. (Elastic<\/a>, Microsoft Learn<\/a>)<\/li>\n<\/ul>\n<\/li>\n\n\n\n
- Tomcat<\/strong> on Linux (e.g.,
\/opt\/tomcat<\/code> or distro path like \/usr\/share\/tomcat<\/code>).<\/li>\n\n\n\n- Java 8+<\/strong> (Java 17\/21 are fine); outbound HTTPS (443) to
*.cloud.es.io<\/code>.<\/li>\n\n\n\n- Shell access (sudo) to install files and restart Tomcat.<\/li>\n<\/ul>\n\n\n\n
\nAbout auth<\/strong><\/p>\n\n\n\n\n- Secret token<\/strong>: simple to start, sent in plaintext over TLS (fine when HTTPS). (Elastic<\/a>)<\/li>\n\n\n\n
- APM Agent key (API key)<\/strong>: preferred for production; create in Kibana or via API for least-privilege agent auth. (Elastic<\/a>)<\/li>\n<\/ul>\n<\/blockquote>\n\n\n\n
\n\n\n\n2) Get your APM endpoint & token\/key from Elastic Cloud<\/h1>\n\n\n\n\n- Open your Elastic Cloud deployment<\/li>\n\n\n\n
- Go to Observability \u2192 APM<\/strong> (or APM & Fleet<\/strong>), copy the APM Server URL<\/strong> and either the Secret token<\/strong> or generate an APM Agent key<\/strong>. (Elastic<\/a>, Microsoft Learn<\/a>)<\/li>\n<\/ol>\n\n\n\n
\n\n\n\n3) Download the Elastic APM Java Agent<\/h1>\n\n\n\n
Create a directory for the agent and download the current jar:<\/p>\n\n\n
sudo mkdir -p \/opt\/elastic\/apm\n# (Replace <version<\/span>><\/span> with the latest, e.g., 1.46.0)\nsudo curl -L -o \/opt\/elastic\/apm\/elastic-apm-agent-<version<\/span>><\/span>.jar \\\n \"https:\/\/search.maven.org\/remotecontent?filepath=co\/elastic\/apm\/elastic-apm-agent\/<version<\/span>><\/span>\/elastic-apm-agent-<version<\/span>><\/span>.jar\"\nsudo chmod 644 \/opt\/elastic\/apm\/elastic-apm-agent-<version<\/span>><\/span>.jar\n<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n\nThe agent jar is published by Elastic; latest versions and source are here if you need to verify: elastic\/apm-agent-java<\/strong>. (GitHub<\/a>)<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n4) (Recommended) Keep credentials out of ps<\/code> output<\/h1>\n\n\n\nCreate a tiny env file readable only by root\/Tomcat that holds your token or API key:<\/p>\n\n\n
# Pick ONE: secret token OR API key<\/span>\n# Secret token variant<\/span>\nsudo bash -c 'cat >\/etc\/elastic-apm.env'<\/span> <<'EOF'<\/span>\nELASTIC_APM_SECRET_TOKEN=YOUR_SECRET_TOKEN_HERE\n# or, API key variant (preferred)<\/span>\n# ELASTIC_APM_API_KEY=YOUR_API_KEY_HERE<\/span>\nEOF\nsudo chmod 600<\/span> \/etc\/elastic-apm.env\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nYou\u2019ll reference this file from setenv.sh<\/code> so the secrets don\u2019t appear in process lists.<\/p>\n\n\n\n
\n\n\n\n5) Wire the agent into Tomcat (setenv.sh)<\/h1>\n\n\n\n
Tomcat reads a setenv.sh<\/code><\/strong> (same folder as catalina.sh<\/code>) on startup. Create it if missing.<\/p>\n\n\n# Find your Tomcat base; examples:<\/span>\n# export CATALINA_HOME=\/opt\/tomcat<\/span>\n# or distro paths like \/usr\/share\/tomcat or \/usr\/share\/tomcat9<\/span>\ncd \"$CATALINA_HOME\/bin\"<\/span>\n\nsudo bash -c 'cat >setenv.sh'<\/span> <<'EOF'<\/span>\n#!\/usr\/bin\/env bash<\/span>\n# Load secrets<\/span>\n[ -f \/etc\/elastic-apm.env ] && . \/etc\/elastic-apm.env\n\n# Path to the agent<\/span>\nAGENT_JAR=\"\/opt\/elastic\/apm\/elastic-apm-agent-<version>.jar\"<\/span>\n\n# Core APM config (minimal)<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -javaagent:${AGENT_JAR}\"<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.service_name=my-tomcat-app\"<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.server_url=https:\/\/<your-cloud-apm-endpoint>:443\"<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.environment=prod\"<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.application_packages=com.yourcompany,org.example\"<\/span>\n\n# Auth: use ONE of the following (API key preferred)<\/span>\n# Secret token<\/span>\n[ -n \"$ELASTIC_APM_SECRET_TOKEN\"<\/span> ] && \\\n CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.secret_token=${ELASTIC_APM_SECRET_TOKEN}\"<\/span>\n# API key<\/span>\n[ -n \"$ELASTIC_APM_API_KEY\"<\/span> ] && \\\n CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.api_key=${ELASTIC_APM_API_KEY}\"<\/span>\n\n# Useful production defaults \/ hygiene<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.capture_body=errors\"<\/span>\nCATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.global_labels=org=MyCo,team=platform,region=jp\"<\/span>\n# (Log correlation is ON by default in recent agent versions)<\/span>\n# CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.log_level=info\"<\/span>\n\nexport CATALINA_OPTS\nEOF\n\nsudo chmod +x setenv.sh\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nWhy these options?<\/strong><\/p>\n\n\n\n\nservice_name<\/code>, server_url<\/code>, application_packages<\/code> are the key minimums for Java agent. (Elastic<\/a>)<\/li>\n\n\n\nglobal_labels<\/code> adds useful searchable tags across all APM events. (Elastic<\/a>)<\/li>\n\n\n\n- Log correlation<\/strong> with your logs is enabled by default in agent \u2265 1.30 (no extra flag needed). (Elastic<\/a>)<\/li>\n<\/ul>\n\n\n\n
\nIf you prefer central configuration<\/strong> (set most options from Kibana APM UI), that\u2019s also supported and can override local settings. (Elastic<\/a>)<\/p>\n<\/blockquote>\n\n\n\n
\n\n\n\n6) Restart Tomcat<\/h1>\n\n\n\n
For a tarball install:<\/p>\n\n\n
$CATALINA_HOME\/bin\/shutdown.sh || true<\/span>\n$CATALINA_HOME\/bin\/startup.sh\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nFor a systemd install:<\/p>\n\n\n
sudo systemctl daemon-reload\nsudo systemctl restart tomcat # or tomcat9, etc.<\/span>\nsudo journalctl -u tomcat -f\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nYou should see the agent initialize in catalina.out<\/code>\/service logs.<\/p>\n\n\n\n
\n\n\n\n7) Generate traffic & verify in Kibana<\/h1>\n\n\n\n\n- Hit a few app endpoints (e.g., your web app pages or APIs).<\/li>\n\n\n\n
- In Kibana \u2192 Observability \u2192 APM \u2192 Services<\/strong>, your
service_name<\/code> should appear with transactions and traces. (Elastic<\/a>)<\/li>\n<\/ul>\n\n\n\nConnectivity check (optional):<\/strong><\/p>\n\n\n# Quick probe that APM server is up (expects 200)<\/span>\ncurl -s -o \/dev\/null<\/span> -w \"%{http_code}\\n\"<\/span> https:\/\/<your-cloud-apm-endpoint>\/<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\nThe APM Server Information<\/strong> endpoint returns 200 when reachable. (Auth is still required by the agent for sending data.) (Elastic<\/a>)<\/p>\n\n\n\n
\n\n\n\n8) Production hardening & nice-to-haves<\/h1>\n\n\n\n\n- Use an APM Agent key<\/strong> instead of a secret token for better control\/rotation. (Elastic<\/a>)<\/li>\n\n\n\n
- Sampling<\/strong>: adjust volume vs. detail
-Delastic.apm.transaction_sample_rate=0.2 # 20% traces<\/code><\/li>\n\n\n\n- Sensitive data<\/strong>: keep request bodies off by default (
capture_body=off<\/code>) or restrict to errors<\/code>\/transactions<\/code> only; you can fine-tune per endpoint in Kibana later. (Elastic<\/a>)<\/li>\n\n\n\n- Proxies \/ firewalls<\/strong>: ensure egress to your Cloud APM URL:443; add standard JVM proxy flags if needed (
-Dhttps.proxyHost<\/code>, -Dhttps.proxyPort<\/code>).<\/li>\n\n\n\n- Multiple apps on one Tomcat<\/strong>: use separate
service_name<\/code> per instance (simplest via separate start wrappers\/env). (Stack Overflow<\/a>)<\/li>\n\n\n\n- Central config<\/strong>: once data flows, you can flip tuning options in Kibana APM without restarts. (Elastic<\/a>)<\/li>\n<\/ul>\n\n\n\n
\n\n\n\n9) Troubleshooting checklist<\/h1>\n\n\n\n\n- Agent loaded?<\/strong> Look for \u201cElastic APM agent initialized\u201d in Tomcat logs.<\/li>\n\n\n\n
- Auth errors?<\/strong> Re-copy the Secret token<\/strong> or APM Agent key<\/strong> from Kibana; mismatches are the most common issue. (Elastic<\/a>)<\/li>\n\n\n\n
- Endpoint reachable?<\/strong>
curl<\/code> the APM server URL as above; if blocked, fix firewall\/egress rules. (Elastic<\/a>)<\/li>\n\n\n\n- Verbose logs (temporarily):<\/strong>
CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.log_level=debug\"<\/code><\/li>\n\n\n\n- Handshake\/SSL issues?<\/strong> The agent uses your JVM CA truststore; ensure up-to-date CA certificates.<\/li>\n\n\n\n
- No services showing?<\/strong> Make sure
service_name<\/code> is set and generate a few real requests. (Elastic<\/a>)<\/li>\n<\/ul>\n\n\n\n
\n\n\n\n10) Copy-paste example (using your values)<\/h1>\n\n\n\n\nNote:<\/strong> replace placeholder values; keep your token\/key secret.<\/p>\n<\/blockquote>\n\n\n# \/opt\/tomcat\/bin\/setenv.sh (snippet)<\/span>\nexport CATALINA_OPTS=\"$CATALINA_OPTS -javaagent:\/opt\/elastic\/apm\/elastic-apm-agent-<version>.jar\"<\/span>\nexport CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.service_name=my-service-name\"<\/span>\nexport CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.server_url=https:\/\/fb97fae75f1b43b4b6ccfc4921e8b13d.apm.us-central1.gcp.cloud.es.io:443\"<\/span>\nexport CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.environment=my-environment\"<\/span>\nexport CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.application_packages=org.example\"<\/span>\n# ONE of the following:<\/span>\nexport CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.secret_token=********\"<\/span>\n# export CATALINA_OPTS=\"$CATALINA_OPTS -Delastic.apm.api_key=********\"<\/span>\n<\/code><\/span>Code language:<\/span> PHP<\/span>