APM Server 二进制文件

本指南将解释如何设置和配置 APM Server 二进制文件。

首先，请参阅 Elastic 支持矩阵，了解有关受支持的操作系统和产品兼容性的信息。

您需要

• Elasticsearch，用于存储和索引数据。
• Kibana，用于通过应用程序 UI 进行可视化。

建议使用相同版本的 Elasticsearch、Kibana 和 APM Server。有关安装这些产品的更多信息，请参阅部署。

×

要下载并安装 APM Server，请使用适合您系统的以下命令。如果您使用 apt 或 yum，可以从我们的存储库安装 APM Server，以便更轻松地更新到最新版本。

deb：

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-9.4.4-amd64.deb
sudo dpkg -i apm-server-9.4.4-amd64.deb
		

RPM：

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-9.4.4-x86_64.rpm
sudo rpm -vi apm-server-9.4.4-x86_64.rpm
		

其他 Linux：

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-9.4.4-linux-x86_64.tar.gz
tar xzvf apm-server-9.4.4-linux-x86_64.tar.gz
		

有关更多信息，请参阅修改 nofile ulimit。

Mac：

curl -L -O https://artifacts.elastic.co/downloads/apm-server/apm-server-9.4.4-darwin-x86_64.tar.gz
tar xzvf apm-server-9.4.4-darwin-x86_64.tar.gz
		

Windows：

1. 从下载页面下载 APM Server Windows zip 文件。

2. 将 zip 文件的内容解压到 C:\Program Files 中。

3. 将 apm-server-<version>-windows 目录重命名为 APM-Server。

4. 以管理员身份打开 PowerShell 提示符（右键单击 PowerShell 图标并选择以管理员身份运行）。如果您使用的是 Windows XP，可能需要下载并安装 PowerShell。

5. 在 PowerShell 提示符中，运行以下命令将 APM Server 作为 Windows 服务安装

Docker：

有关部署 Docker 容器的信息，请参阅在 Docker 上运行。

通过编辑 apm-server.yml 配置文件来配置 APM。该文件的位置因平台而异——如需查找帮助，请参阅安装布局。

最小配置文件可能如下所示

apm-server:
  host: "localhost:8200"
output.elasticsearch:
  hosts: ["localhost:9200"]
  username: "elastic"
  password: "changeme"
		

1. APM Server 监听的 host:port。
2. 要连接的 Elasticsearch host:port。
3. 本示例使用基本身份验证。此处提供的用户需要将事件发布到 Elasticsearch 所需的权限。要为此角色创建专用用户，请参阅创建 writer 角色。

所有可用的配置选项已在配置 APM Server中概述。

在生产环境中，您会将 APM Server 部署在独立的机器上，这与运行 Elasticsearch 类似。您可以将其与 Elasticsearch 运行在同一台机器上，但并不推荐这样做，因为这些进程会互相竞争资源。

要启动 APM Server，请运行

./apm-server -e
		

您应该会看到 APM Server 启动。它将尝试连接到本地主机端口 9200 上的 Elasticsearch，并在端口 8200 上向 Agent 暴露 API。您可以在 apm-server.yml 中更改默认值，或在命令行中指定不同的地址

./apm-server -e -E output.elasticsearch.hosts=ElasticsearchAddress:9200 -E apm-server.host=localhost:8200
		

对于 Debian 软件包和 RPM 安装，我们建议 apm-server 进程作为非 root 用户运行。因此，这些安装方法会创建一个 apm-server 用户，您可以使用该用户来启动进程。此外，仅当配置文件属于运行该进程的用户时，APM Server 才会启动。

在此情况下，要启动 APM Server，请运行

sudo -u apm-server apm-server [<argument...>]
		

默认情况下，APM Server 从 /etc/apm-server/apm-server.yml 加载其配置文件。有关完整的目录布局，请参阅 deb 和 rpm 默认路径。

// Android app's build.gradle file
plugins {
    id "com.android.application"
    id "co.elastic.apm.android" version "[latest_version]"
}
		

// Android app's build.gradle file
plugins {
    //...
    id "co.elastic.apm.android" version "[latest_version]"
}

elasticApm {
    // Minimal configuration
    serverUrl = "https://your.elastic.server"

    // Optional
    serviceName = "your app name"
    serviceVersion = "0.0.0"
    apiKey = "your server api key"
    secretToken = "your server auth token"
}
		

// Your Application class

class MyApp extends android.app.Application {

    @Override
    public void onCreate() {
        super.onCreate();
        ElasticApmAgent.initialize(this);
    }
}
		

go get -u go.elastic.co/apm/v2
		

# The APM integration host and port
export ELASTIC_APM_SERVER_URL=

# If you do not specify `ELASTIC_APM_SERVICE_NAME`, the Go agent will use the
# executable name. For example, if your executable is called "my-app.exe", then your
# service will be identified as "my-app".
export ELASTIC_APM_SERVICE_NAME=

# Secret tokens are used to authorize requests to the APM integration
export ELASTIC_APM_SECRET_TOKEN=
		

Package(
    dependencies:[
         .package(name: "apm-agent-ios", url: "https://github.com/elastic/apm-agent-ios.git", from: "1.0.0"),
    ],
  targets:[
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "ElasticApm", package: "apm-agent-ios")
        ]
    ),
])
		

import SwiftUI
import ElasticApm

class AppDelegate : NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        var config = AgentConfigBuilder()
            .withServerUrl(URL(string:"http://127.0.0.1:8200"))
            .withSecretToken("<SecretToken>")
            .build()

        ElasticApmAgent.start(with: config)
        return true
    }
}

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    init() {
    }
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
		

import UIKit
import ElasticApm
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
var config = AgentConfigBuilder()
                       .withServerUrl(URL(string:"http://127.0.0.1:8200"))
                       .withSecretToken("<SecretToken>")
                       .build()
        ElasticApmAgent.start(with: config)
        return true
    }
}
		

java -javaagent:/path/to/elastic-apm-agent-<version>.jar -Delastic.apm.service_name=my-cool-service -Delastic.apm.application_packages=org.example,org.another.example -Delastic.apm.server_url=http://127.0.0.1:8200 -jar my-application.jar
		

npm install elastic-apm-node --save
		

// Add this to the VERY top of the first file loaded in your app
var apm = require('elastic-apm-node').start({
  // Override service name from package.json
  // Allowed characters: a-z, A-Z, 0-9, -, _, and space
  serviceName: '',

  // Use if APM integration requires a token
  secretToken: '',

  // Use if APM integration uses API keys for authentication
  apiKey: '',

  // Set custom APM integration host and port (default: http://127.0.0.1:8200)
  serverUrl: '',
})
		

rpm -ivh <package-file>.rpm
		

dpkg -i <package-file>.deb
		

apk add --allow-untrusted <package-file>.apk
		

cd apm-agent-php
# for linux glibc - libc distributions (Ubuntu, Redhat, etc)
export BUILD_ARCHITECTURE=linux-x86-64
# for linux with musl - libc distributions (Alpine)
export BUILD_ARCHITECTURE=linuxmusl-x86-64
# provide a path to php-config tool
export PHP_CONFIG=php-config

# build extensions
make -f .ci/Makefile build

# run extension tests
PHP_VERSION=`$PHP_CONFIG --version | cut -d'.' -f 1,2` make -f .ci/Makefile run-phpt-tests

# install agent extensions
sudo cp agent/native/_build/${BUILD_ARCHITECTURE}-release/ext/elastic_apm-*.so `$PHP_CONFIG --extension-dir`

# install automatic loader
sudo cp agent/native/_build/${BUILD_ARCHITECTURE}-release/loader/code/elastic_apm_loader.so `$PHP_CONFIG --extension-dir`
		

extension=elastic_apm_loader.so
elastic_apm.bootstrap_php_part_file=<repo root>/agent/php/bootstrap_php_part.php
		

$ pip install elastic-apm
		

# Add the agent to the installed apps
INSTALLED_APPS = (
  'elasticapm.contrib.django',
  # ...
)

ELASTIC_APM = {
  # Set required service name. Allowed characters:
  # a-z, A-Z, 0-9, -, _, and space
  'SERVICE_NAME': '',

  # Use if APM integration requires a token
  'SECRET_TOKEN': '',

  # Set custom APM integration host and port (default: https://:8200)
  'SERVER_URL': '',
}

# To send performance metrics, add our tracing middleware:
MIDDLEWARE = (
  'elasticapm.contrib.django.middleware.TracingMiddleware',
  #...
)
		

$ pip install elastic-apm[flask]
		

# initialize using environment variables
from elasticapm.contrib.flask import ElasticAPM
app = Flask(__name__)
apm = ElasticAPM(app)

# or configure to use ELASTIC_APM in your application settings
from elasticapm.contrib.flask import ElasticAPM
app.config['ELASTIC_APM'] = {
  # Set required service name. Allowed characters:
  # a-z, A-Z, 0-9, -, _, and space
  'SERVICE_NAME': '',

  # Use if APM integration requires a token
  'SECRET_TOKEN': '',

  # Set custom APM integration host and port (default: https://:8200)
  'SERVER_URL': '',
}

apm = ElasticAPM(app)
		

gem 'elastic-apm'
		

# config/elastic_apm.yml:

# Set service name - allowed characters: a-z, A-Z, 0-9, -, _ and space
# Defaults to the name of your Rails app
service_name: 'my-service'

# Use if APM integration requires a token
secret_token: ''

# Set custom APM integration host and port (default: https://:8200)
server_url: 'https://:8200'
		

# config.ru

app = lambda do |env|
  [200, {'Content-Type' => 'text/plain'}, ['ok']]
end

# Wraps all requests in transactions and reports exceptions
use ElasticAPM::Middleware

# Start an instance of the Agent
ElasticAPM.start(service_name: 'NothingButRack')

run app

# Gracefully stop the agent when process exits.
# Makes sure any pending transactions are sent.
at_exit { ElasticAPM.stop }
		

# config/elastic_apm.yml:

# Set service name - allowed characters: a-z, A-Z, 0-9, -, _ and space
# Defaults to the name of your Rack app's class.
service_name: 'my-service'

# Use if APM integration requires a token
secret_token: ''

# Set custom APM integration host and port (default: https://:8200)
server_url: 'https://:8200'
		

<script src="<YOUR_URL>/path/to/elastic-apm-rum.umd.min-<VERSION>.js" crossorigin></script>
<script>
  elasticApm.init({
    serviceName: '<instrumented-app>',
    serverUrl: '<apm-server-url>',
  })
</script>
		

<script>
  ;(function(d, s, c) {
    var j = d.createElement(s),
      t = d.getElementsByTagName(s)[0]

    j.src = '<YOUR_URL>/path/to/elastic-apm-rum.umd.min-<VERSION>.js'
    j.onload = function() {elasticApm.init(c)}
    t.parentNode.insertBefore(j, t)
  })(document, 'script', {serviceName: '<INSTRUMENTED_APP>', serverUrl: '<APM_SERVER_URL>'})
</script>
		

npm install @elastic/apm-rum --save
		

import { init as initApm } from '@elastic/apm-rum'

const apm = initApm({

  // Set required service name (allowed characters: a-z, A-Z, 0-9, -, _, and space)
  serviceName: '',

  // Set custom APM integration host and port (default: https://:8200)
  serverUrl: 'https://:8200',

  // Set service version (required for sourcemap feature)
  serviceVersion: ''
})
		

当您至少有一个 APM Agent 向 APM Server 发送数据后，就可以开始在 Kibana 应用程序 UI 中可视化您的数据了。

×

我们为基于 APT 和 YUM 的发行版提供软件仓库。请注意，我们只提供二进制包，不提供源码包。

我们使用 PGP 密钥 D88E42B4（Elasticsearch 签名密钥），其指纹为

4609 5ACC 8548 582C 1A26 99A9 D27D 666C D88E 42B4
		

来对我们所有的软件包进行签名。该密钥可从 https://pgp.mit.edu 获取。

要为 APT 添加 apm-server 存储库

1. 下载并安装公共签名密钥

   wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
   		

2. 在继续操作之前，您可能需要在 Debian 上安装 apt-transport-https 软件包

   sudo apt-get install apt-transport-https
   		

3. 将存储库定义保存到 /etc/apt/sources.list.d/elastic-9.0.0.list

   echo "deb https://artifacts.elastic.co/packages/9.0.0-prerelease/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-9.0.0-prerelease.list
   		

   警告

   要添加 Elastic 软件仓库，请确保使用示例中显示的 echo 方法。不要使用 add-apt-repository，因为它会添加一个 deb-src 条目，而我们不提供源码包。

   如果你不小心添加了 deb-src 条目，将会看到类似以下的错误

   Unable to find expected entry 'main/source/Sources' in Release file (Wrong sources.list entry or malformed file)
   		

4. 运行 apt-get update，存储库即可使用。例如，您可以通过运行以下命令来安装 APM Server

   sudo apt-get update && sudo apt-get install apm-server
   		

5. 要配置 APM Server 在开机时自动启动，请运行

   sudo systemctl enable apm-server
   		

要为 YUM 添加 apm-server 存储库

1. 下载并安装公共签名密钥

   sudo rpm --import https://packages.elastic.co/GPG-KEY-elasticsearch
   		

2. 在 /etc/yum.repos.d/ 目录中创建一个带有 .repo 扩展名的文件（例如 elastic.repo），并添加以下行

   [elastic-9.0.0]
   name=Elastic repository for 9.0.0 packages
   baseurl=https://artifacts.elastic.co/packages/9.0.0/yum
   gpgcheck=1
   gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
   enabled=1
   autorefresh=1
   type=rpm-md
   		

   您的存储库已准备就绪。例如，您可以通过运行以下命令来安装 APM Server

   sudo yum install apm-server
   		

3. 要配置 APM Server 在开机时自动启动，请运行

   sudo systemctl enable apm-server
   		

APM Server 的 Docker 镜像可从 Elastic Docker 注册表中获取。基础镜像是 Red Hat Universal Base Images (UBI)，如果您使用经过加固的 Docker 镜像，则为 Wolfi。

所有已发布的 Docker 镜像及标签列表可在 www.docker.elastic.co 查看。

根据 Elastic 许可证，这些镜像是可以免费使用的。它们包含开源和免费的商业功能，以及访问付费商业功能的权限。开启 30 天试用以体验所有付费商业功能。有关 Elastic 许可证级别的详细信息，请参阅订阅页面。

获取 Docker 版 APM Server 非常简单，只需对 Elastic Docker 注册表执行 docker pull 命令，然后（可选）验证镜像。

1. 拉取 Docker 镜像

   docker pull docker.elastic.co/apm/apm-server:9.0.0
   		

   或者，您可以使用经过加固的 Wolfi 镜像

   docker pull docker.elastic.co/apm/apm-server-wolfi:9.0.0
   		

2. 验证 Docker 镜像

   wget https://artifacts.elastic.co/cosign.pub
   cosign verify --key cosign.pub docker.elastic.co/apm/apm-server:9.0.0
   		

   cosign 命令以 JSON 格式打印检查结果和签名有效负载

   Verification for docker.elastic.co/apm/apm-server:9.0.0 --
   The following checks were performed on each of these signatures:
     - The cosign claims were validated
     - Existence of the claims in the transparency log was verified offline
     - The signatures were verified against the specified public key
   		

Docker 镜像提供了几种配置 APM Server 的方法。传统做法是通过卷挂载提供配置文件，但也可以创建一个包含您的配置的自定义镜像。

下载此示例配置文件作为起点

curl -L -O https://raw.githubusercontent.com/elastic/apm-server/master/apm-server.docker.yml
		

在 Docker 上配置 APM Server 的一种方法是通过卷挂载提供 apm-server.docker.yml。在 docker run 命令中，卷挂载可以像这样指定。

docker run -d \
  -p 8200:8200 \
  --name=apm-server \
  --user=apm-server \
  --volume="$(pwd)/apm-server.docker.yml:/usr/share/apm-server/apm-server.yml:ro" \
  docker.elastic.co/apm/apm-server:9.0.0 \
  --strict.perms=false -e \
  -E output.elasticsearch.hosts=["elasticsearch:9200"] <1>
		

1. 替换您的 Elasticsearch 主机与端口。
2. 如果您使用的是 Elastic Cloud Hosted，请使用前面显示的语法将 -E output.elasticsearch.hosts 行替换为 Cloud ID 和 elastic 密码。

之前下载的 apm-server.docker.yml 应当根据您的环境进行自定义。更多详情请参阅配置 APM Server。编辑配置文件并根据您的环境自定义，然后重新部署 APM Server 容器。

也可以将 APM Server 配置嵌入到自定义镜像中。以下是实现此目的的示例 Dockerfile

FROM docker.elastic.co/apm/apm-server:9.0.0
COPY --chmod=0644 --chown=1000:1000 apm-server.yml /usr/share/apm-server/apm-server.yml
		

您可以在命令行中使用 --ulimit=soft:hard 来设置 nofile ulimit。有关详细信息，请参阅 Docker 文档中的在容器中设置 ulimit (--ulimit)。

docker run -d \
  -p 8200:8200 \
  --name=apm-server \
  --user=apm-server \
  --volume="$(pwd)/apm-server.docker.yml:/usr/share/apm-server/apm-server.yml:ro" \
  docker.elastic.co/apm/apm-server:9.0.0 \
  --strict.perms=false -e \
  --ulimit=524287:524287 \
  -E output.elasticsearch.hosts=["elasticsearch:9200"] <1>
		

1. 替换为您的 Elasticsearch 主机和端口。
2. 如果您使用的是 Elastic Cloud 托管服务，请如上例所示，将 -E output.elasticsearch.hosts 行替换为 Cloud ID 和 Elastic 密码。

当作为独立二进制文件运行 APM Server 时，它会从运行该进程的用户处继承 nofile 限制。在大多数系统上，此限制设置为 1024，这对于高吞吐量场景或使用基于尾部的采样时来说太低了。

要选择合适的限制，请考虑以下事项

• 1024 的限制通常对于低吞吐量用例来说足够了。
• 不设置限制不会带来性能方面的负面影响。
• 打开文件的主要来源是传入连接的数量。
• 基于尾部的采样是基于文件的，并且会随着吞吐量和采样策略按比例增加打开文件的数量。

要为您的用户配置限制

1. 确定运行 APM Server 进程的用户

whoami
		

2. 以 root 权限编辑 /etc/security/limits.conf

sudo nano /etc/security/limits.conf
		

添加以下行以设置您的用户的软限制和硬限制

apm-server soft nofile 524287
apm-server hard nofile 524287
		

1. 将 apm-server 替换为您用来运行 APM Server 进程的用户名。

要修改正在运行的 APM Server 进程的 nofile 限制

1. 获取进程 ID (PID)

pgrep -f apm-server
		

2. 应用新限制

prlimit --pid PID --nofile=524287:524287
		

1. 将 PID 替换为您的 APM Server 进程 ID。