html/get-started/6.5/install-and-run.html

<!DOCTYPE html>
<html lang="en-us">
  <head>
    
<meta charset="UTF-8">
<title>Install and run Elastic APM | APM Overview [6.5] | Elastic</title>
<meta class="elastic" name="content" content="Install and run Elastic APM | APM Overview [6.5]">

<link rel="home" href="index.html" title="APM Overview [6.5]"/>
<link rel="up" href="index.html" title="APM Overview [6.5]"/>
<link rel="prev" href="distributed-tracing.html" title="Distributed tracing"/>
<link rel="next" href="agent-server-compatibility.html" title="Agent/Server Compatibility"/>
<meta class="elastic" name="product_version" content="6.5"/>
<meta class="elastic" name="product_name" content="APM"/>
<meta class="elastic" name="website_area" content="documentation"/>
<meta name="DC.type" content="Learn/Docs/APM Server/Reference/6.5"/>
<meta name="DC.subject" content="APM"/>
<meta name="DC.identifier" content="6.5"/>
<meta name="robots" content="noindex,nofollow"/>

    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd" />
    <meta name="yandex-verification" content="d8a47e95d0972434" />
    <meta name="localized" content="true" />
    <meta name="st:robots" content="follow,index" />
    <meta property="og:image" content="https://static-www.elastic.co/v3/assets/bltefdd0b53724fa2ce/blt280217a63b82a734/6202d3378b1f312528798412/elastic-logo.svg" />
    <meta property="og:image:width" content="500" />
    <meta property="og:image:height" content="172" />
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles-v1.css" />
  </head>

  <!--© 2015-2025 Elasticsearch B.V. -->
  <!-- All Elastic documentation is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License. -->
  <!-- http://creativecommons.org/licenses/by-nc-nd/4.0/ -->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!-- Google Tag Manager for GA4 -->
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','GTM-KNJMG2M');</script>
    <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-KNJMG2M" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <!-- End Google Tag Manager for GA4-->

    <div id='elastic-nav' style="display:none;"></div>
    <script src='https://www.elastic.co/elastic-nav.js'></script>

    <div class="main-container">
      <section id="content" >
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container-fluid">
              <div class="row pb-3">
                <div class="col-12 order-2 col-md-4 order-md-1 col-lg-3 h-almost-full-md sticky-top-md" id="left_col">
                  <!-- The TOC is appended here -->
                </div>

                <div class="col-12 order-1 col-md-8 order-md-2 col-lg-7 order-lg-2 guide-section" id="middle_col">
                  <!-- start body -->
                  
<div class="page_header">
A newer version is available. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div class="navheader">
<span class="prev">
<a href="distributed-tracing.html">« Distributed tracing</a>
</span>
<span class="next">
<a href="agent-server-compatibility.html">Agent/Server Compatibility »</a>
</span>
</div>
<div class="book" lang="en">
<div class="titlepage">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="/guide/">Elastic Docs</a></span>
<span class="chevron-right">›</span><span class="breadcrumb-link">
  <div id="related-products" class="dropdown">
  <div class="related-products-title">APM:</div>
  <div class="dropdown-anchor" tabindex="0">Overview<span class="dropdown-icon"></span></div>
  <div class="dropdown-content">
  <ul>
  <li class="dropdown-category">APM</li>
  <ul>
  <li><a href="/guide/en/observability/current/apm.html">Observability › APM</a></li>
  </ul>
  <li class="dropdown-category">APM agents</li>
  <ul>
  <li><a href="/guide/en/apm/agent/android/current/intro.html">Android Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/go/current/introduction.html">Go Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/swift/current/intro.html">iOS Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/java/current/intro.html">Java Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/dotnet/current/intro.html">.NET Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/nodejs/current/intro.html">Node.js Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/php/current/intro.html">PHP Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/python/current/getting-started.html">Python Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/ruby/current/introduction.html">Ruby Agent Reference</a></li>
  <li><a href="/guide/en/apm/agent/rum-js/current/intro.html">Real User Monitoring JavaScript Agent Reference</a></li>
  </ul>
  <li class="dropdown-category">APM extensions</li>
  <ul>
  <li><a href="/guide/en/apm/lambda/current/aws-lambda-arch.html">AWS Lambda extension</a></li>
  <li><a href="/guide/en/apm/attacher/current/apm-attacher.html">Attacher</a></li>
  </ul>
  </ul>
  </div>
  </div>
</div>
<div>
<div><h1 class="title"><a id="id-1"></a>Install and run Elastic APM</h1><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
</div>
<!--EXTRA-->
</div>
<div id="content">
<div id="url-to-v3" class="version-warning">
    <strong>IMPORTANT</strong>: This documentation is no longer updated. Refer to <a href="https://www.elastic.co/support/eol">Elastic's version policy</a> and the <a href="https://www.elastic.co/docs">latest documentation</a>.
</div>
<div class="chapter">
<div class="titlepage"><div><div>
<div class="position-relative"><h2 class="title"><a id="install-and-run"></a>Install and run Elastic APM</h2><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
</div></div></div>
<p>To get started using Elastic APM,
you need to have:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a href="/guide/en/apm/agent/index.html" class="ulink" target="_top">APM agents</a> installed in your services
</li>
<li class="listitem">
<a href="/guide/en/apm/server/6.5/index.html" class="ulink" target="_top">APM Server</a>
</li>
<li class="listitem">
<a href="/guide/en/elasticsearch/reference/6.5/index.html" class="ulink" target="_top">Elasticsearch</a>
</li>
<li class="listitem">
<a href="/guide/en/kibana/6.5" class="ulink" target="_top">Kibana</a>
</li>
</ul>
</div>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>For best results, ensure you&#8217;re using the same version of Elasticsearch, Kibana, and APM Server.</p>
</div>
</div>
<p>First, you&#8217;ll need to install and start an Elasticsearch cluster and Kibana. Information on how to do this can be found in the <a href="/guide/en/elastic-stack-get-started/6.5/get-started-elastic-stack.html" class="ulink" target="_top">Elastic Stack getting started guide</a>. Specifically, the <a href="/guide/en/elastic-stack-get-started/6.5/get-started-elastic-stack.html#install-elasticsearch" class="ulink" target="_top">install Elasticsearch</a>, and <a href="/guide/en/elastic-stack-get-started/6.5/get-started-elastic-stack.html#install-kibana" class="ulink" target="_top">install Kibana</a> sections.</p>
<p>The following sections show how to get started quickly with Elastic APM on a local machine.</p>
<div class="position-relative"><h3><a id="apm-server"></a>Install and run APM Server</h3><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>First, <a href="/downloads/apm/apm-server" class="ulink" target="_top">download APM Server</a> for your operating system and extract the package.</p>
<p>In a production environment you would put APM Server on its own machines,
similar to how you run Elasticsearch.
You <em>can</em> run it on the same machines as Elasticsearch,
but this is not recommended,
as the processes will be competing for resources.</p>
<p>To start APM Server, run:</p>
<div class="pre_wrapper lang-bash">
<div class="console_code_copy" title="Copy to clipboard"></div>
<pre class="programlisting prettyprint lang-bash">./apm-server -e</pre>
</div>
<p>It will try to connect to Elasticsearch on localhost port 9200 and expose an API to agents on port 8200.
You can change the defaults by supplying different addresses on the command line:</p>
<div class="pre_wrapper lang-bash">
<div class="console_code_copy" title="Copy to clipboard"></div>
<pre class="programlisting prettyprint lang-bash">./apm-server -e -E output.elasticsearch.hosts=ElasticsearchAddress:9200 -E apm-server.host=localhost:8200</pre>
</div>
<p>Or you can update the <code class="literal">apm-server.yml</code> configuration file:</p>
<div class="pre_wrapper lang-yaml">
<div class="console_code_copy" title="Copy to clipboard"></div>
<pre class="programlisting prettyprint lang-yaml">apm-server:
  host: localhost:8200

output:
  elasticsearch:
    hosts: ElasticsearchAddress:9200</pre>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you are using an X-Pack secured version of Elastic Stack,
you need to specify credentials in the config file:</p>
</div>
</div>
<div class="pre_wrapper lang-yaml">
<div class="console_code_copy" title="Copy to clipboard"></div>
<pre class="programlisting prettyprint lang-yaml">output.elasticsearch:
  hosts: ["ElasticsearchAddress:9200"]
  username: "elastic"
  password: "elastic"</pre>
</div>
<div class="position-relative"><h4><a id="secure-api-access"></a>Secure access to the API</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>If you change the listen address from <code class="literal">localhost</code> to something that is accessible from outside of the machine,
we recommend setting up firewall rules to ensure that only your own systems can access the API.
Alternatively,
you can use a <a href="/guide/en/apm/server/6.5/securing-apm-server.html" class="ulink" target="_top">secret token and TLS</a>.</p>
<p>If you have APM Server running on the same host as your service, you can configure it to listen on a Unix domain socket.</p>
<div class="position-relative"><h4><a id="kibana-dashboards"></a>Install the Kibana dashboards</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>From APM Server and Kibana 6.4 on you can load dashboards directly via the <a href="/guide/en/kibana/6.5/apm-getting-started.html" class="ulink" target="_top">APM
Kibana UI</a>.</p>
<p>See an example screenshot of a Kibana dashboard:</p>
<div class="imageblock">
<div class="content">
<img src="kibana-dashboard.png" alt="Screenshot of a Kibana Dashboard">
</div>
</div>
<div class="position-relative"><h3><a id="more-information"></a>More information</h3><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>For detailed instructions on how to install and secure APM Server in your server environment,
including details on how to run APM Server in a highly available environment,
please see <a href="/guide/en/apm/server/6.5/index.html" class="ulink" target="_top">APM Server documentation</a>.</p>
<p>Once APM Server is up and running,
you need to install an agent in your service.</p>
<div class="position-relative"><h3><a id="agents"></a>Install and configure APM agents</h3><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>Agents are written in the same language as your service.
Currently Elastic APM has agents for Node.js, Python, Ruby, Java, Go, and JavaScript RUM.</p>
<p>Setting up a new service to be monitored requires installing the agent,
and configuring it with the address of your APM Server and the service name.</p>
<div class="position-relative"><h4><a id="choose-service-name"></a>Choose a service name</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>The service name is used by Elastic APM to differentiate between data coming from different services.</p>
<p>Elastic APM includes the service name field on every document that it saves in Elasticsearch.
If you change the service name after using Elastic APM,
you will see the old service name and the new service name as two separate services.
Make sure you choose a good service name before you get started.</p>
<p>The service name can only contain alphanumeric characters,
spaces, underscores, and dashes (must match <code class="literal">^[a-zA-Z0-9 _-]+$</code>).</p>
<div class="position-relative"><h4><a id="nodejs-agent"></a>Install the Node.js agent</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>The Node.js agent automatically instruments Express,
hapi,
Koa,
and Restify out of the box.
See the <a href="/guide/en/apm/agent/nodejs/current/index.html" class="ulink" target="_top">APM Node.js Agent documentation</a> for more information.</p>
<div class="position-relative"><h4><a id="python-agent"></a>Install the Python agent</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>The Python agent automatically instruments Django and Flask out of the box.
See the <a href="/guide/en/apm/agent/python/current/index.html" class="ulink" target="_top">APM Python Agent documentation</a> for more information.</p>
<div class="position-relative"><h4><a id="ruby-agent"></a>Install the Ruby agent</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>The Ruby agent automatically instruments Rails out of the box.
See the <a href="/guide/en/apm/agent/ruby/current/index.html" class="ulink" target="_top">APM Ruby Agent documentation</a> for more information.</p>
<div class="position-relative"><h4><a id="java-agent"></a>Install the Java Agent</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>The Java agent automatically instruments Servlet API, Spring MVC, and Spring Boot out of the box.
See the <a href="/guide/en/apm/agent/java/current/index.html" class="ulink" target="_top">APM Java Agent documentation</a> for more information.</p>
<div class="position-relative"><h4><a id="go-agent"></a>Install the Go Agent</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>The Go agent automatically instruments Gorilla and Gin,
as well as support for Go&#8217;s built-in net/http and database/sql drivers.
See the <a href="/guide/en/apm/agent/go/current/index.html" class="ulink" target="_top">APM Go Agent documentation</a> for more information.</p>
<div class="position-relative"><h4><a id="rum-agent"></a>Install the RUM JavaScript agent</h4><a class="edit_me" rel="nofollow" title="Edit this page on GitHub" href="https://github.com/elastic/apm-server/edit/6.5/docs/guide/install-and-run.asciidoc">edit</a></div>
<p>Real User Monitoring (RUM) captures user interactions with clients such as web browsers.
See the <a href="/guide/en/apm/agent/rum-js/current/index.html" class="ulink" target="_top">APM RUM JavaScript Agent documentation</a> for more information.</p>
</div>
</div>
</div><div class="navfooter">
<span class="prev">
<a href="distributed-tracing.html">« Distributed tracing</a>
</span>
<span class="next">
<a href="agent-server-compatibility.html">Agent/Server Compatibility »</a>
</span>
</div>

                  <!-- end body -->
                </div>

                <div class="col-12 order-3 col-lg-2 order-lg-3 h-almost-full-lg sticky-top-lg" id="right_col">
                  <div id="sticky_content">
                    <!-- The OTP is appended here -->
                    <div class="row">
                      <div class="col-0 col-md-4 col-lg-0" id="bottom_left_col"></div>
                      <div class="col-12 col-md-8 col-lg-12">
                        <div id="rtpcontainer">
                          <div class="mktg-promo" id="most-popular">
                            <p class="aside-heading">Most Popular</p>
                            <div class="pb-2">
                              <p class="media-type">Video</p>
                              <a href="https://www.elastic.co/webinars/getting-started-elasticsearch?page=docs&placement=top-video">
                                <p class="mb-0">Get Started with Elasticsearch</p>
                              </a>
                            </div>
                            <div class="pb-2">
                              <p class="media-type">Video</p>
                              <a href="https://www.elastic.co/webinars/getting-started-kibana?page=docs&placement=top-video">
                                <p class="mb-0">Intro to Kibana</p>
                              </a>
                            </div>
                            <div class="pb-2">
                              <p class="media-type">Video</p>
                              <a href="https://www.elastic.co/webinars/introduction-elk-stack?page=docs&placement=top-video">
                                <p class="mb-0">ELK for Logs & Metrics</p>
                              </a>
                            </div>
                          </div>
                        </div>

                        <!-- Feedback widget -->
                        <div id="feedbackWidgetContainer"></div>
                      </div>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


        <div id='elastic-footer'></div>
        <script src='https://www.elastic.co/elastic-footer.js'></script>
        <!-- Footer Section end-->

      </section>
    </div>

    <!-- Feedback modal -->
    <div id="feedbackModalContainer"></div>

    <script src="/guide/static/jquery.js"></script>
    <script type="text/javascript" src="/guide/static/docs-v1.js"></script>
    <script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>