Swift 应用指标

Swift 应用指标监测 Swift 运行时的性能，通过 API 以编程方式提供监测数据，或通过其内置的仪表板以可视化方式提供。

Swift 应用指标提供以下内置数据收集源：

来源	描述
环境	机器和运行时环境信息
CPU	进程和系统 CPU
内存	进程和系统内存使用情况
延迟	Dispatch 队列延迟

SwiftMetricsKitura 添加了额外的收集源：

来源	描述
HTTP	HTTP 指标信息

入门指南

先决条件

Swift 应用指标代理支持以下运行时环境：

Swift v4.2 GA on
- Linux (Ubuntu 14.04, 16.04) 上的 64 位运行时
- macOS (x64) 上的 64 位运行时
Swift v4.1 GA on
- Linux (Ubuntu 14.04, 16.04) 上的 64 位运行时
- macOS (x64) 上的 64 位运行时
Swift v4 GA on
- Linux (Ubuntu 14.04, 16.04) 上的 64 位运行时
- macOS (x64) 上的 64 位运行时
Swift v3.1.1 GA，在以下平台上使用 SwiftMetrics 版本 1.2.5：
- Linux (Ubuntu 14.04, 15.10) 上的 64 位运行时
- macOS (x64) 上的 64 位运行时

安装

可以通过将依赖项添加到 Package.swift 文件并更新目标以包含 SwiftMetrics 作为依赖项来安装 Swift 应用指标。

   dependencies: [
      .package(url: "https://github.com/RuntimeTools/SwiftMetrics.git", from: "2.4.0")
   ]
   ...
   targets: [
      .target(name: "MyApp", dependencies: ["SwiftMetrics"], path: "Sources")]

Swift Package Manager 将自动克隆所需的代码并在程序编译期间构建它。

Linux: swift build
macOS: swift build -Xlinker -lc++

配置 Swift 应用指标

将 Swift 应用指标添加为 Swift 应用程序的依赖项后，您应该在 .build 文件夹中找到一个配置文件，.build/checkouts/SwiftMetrics.git--<id>/swiftmetrics.properties （对于旧版本的 Swift，则在 Packages 目录中，Packages/SwiftMetrics-<version>/swiftmetrics.properties）。这用于配置连接选项、日志记录和数据源选项。

Swift 应用指标将尝试从以下位置（按顺序）加载 swiftmetrics.properties：

当前工作目录。
.build/checkouts/SwiftMetrics.git--<id> 目录（对于旧版本的 Swift，则为 Packages/SwiftMetrics-<version>）。

请注意，默认配置启用了最少的日志记录。

运行 Swift 应用指标

修改您的应用程序

要加载 SwiftMetrics 并获取基本监视 API，请将以下内容添加到应用程序的启动代码中：

import SwiftMetrics

let sm = try SwiftMetrics()
let monitoring = sm.monitor()

如果您还想监视 Kitura HTTP 数据，请改用以下代码：

import SwiftMetrics
import SwiftMetricsKitura

let sm = try SwiftMetrics()
SwiftMetricsKitura(swiftMetricsInstance: sm)
let monitoring = sm.monitor()

Swift 应用指标仪表板

要使用内置仪表板，请将以下代码添加到您的应用程序中：

import SwiftMetrics
import SwiftMetricsDash

// Enable SwiftMetrics Monitoring
let sm = try SwiftMetrics()   

// Pass SwiftMetrics to the dashboard for visualising
let smd = try SwiftMetricsDash(swiftMetricsInstance : sm)

默认情况下，SwiftMetricsDash 将启动自己的 Kitura 服务器，并在 http://<hostname>:<port>/swiftmetrics-dash 下提供页面服务。

应用程序启动时，所使用的端口会记录到控制台中。

SwiftMetricsDash：在端口 8080 上启动

Prometheus 支持

要使用 SwiftMetrics 提供 Prometheus 端点，请将以下代码添加到您的应用程序中：

import SwiftMetrics
import SwiftMetricsPrometheus

// Enable SwiftMetrics Monitoring
let sm = try SwiftMetrics()   

// Pass SwiftMetrics to SwiftMetricsPrometheus
let smp = try SwiftMetricsPrometheus(swiftMetricsInstance : sm)

默认情况下，SwiftMetricsPrometheus 将在 http://<hostname>:<port>/metrics 下提供 Prometheus 端点。

应用程序启动时，所使用的端口会记录到控制台中。

SwiftMetricsPrometheus：在端口 8080 上启动

Swift 应用指标代理

SwiftMetrics() 返回 Swift 应用指标代理 - 它与您的代码并行运行，并接收和发送有关您的应用程序的数据到任何连接的客户端。 sm.monitor() 调用返回一个 Swift 应用指标本地客户端，通过本地连接连接到代理 sm。

然后，您可以使用监视对象来注册回调并请求有关应用程序的信息。

monitoring.on({ (env: InitData) in
   for (key, value) in env {
      print("\(key): \(value)\n")
   }
})

func processCPU(cpu: CPUData) {
   print("\nThis is a custom CPU event response.\n cpu.timeOfSample = \(cpu.timeOfSample),\n cpu.percentUsedByApplication = \(cpu.percentUsedByApplication),\n cpu.percentUsedBySystem = \(cpu.percentUsedBySystem).\n")
}

monitoring.on(processCPU)

为了监视您自己的自定义数据，您需要实现一个结构体，该结构体实现基本的 SwiftMetrics 数据协议 SMData。这没有必需的字段，因此您可以只放入您感兴趣的数据。

private struct SnoozeData: SMData {
   let cycleCount: Int
}

private func snoozeMessage(data: SnoozeData) {
   print("\nAlarm has been ignored for \(data.cycleCount) seconds!\n")
}

monitoring.on(snoozeMessage)

sm.emitData(SnoozeData(cycleCount: 40))

//prints "Alarm has been ignored for 40 seconds!"

API 文档

SwiftMetrics.start()

启动 Swift 应用指标代理。如果代理已经在运行，则此函数不执行任何操作。

SwiftMetrics.stop()

停止 Swift 应用指标代理。如果代理未运行，则此函数不执行任何操作。

SwiftMetrics.setPluginSearch(toDirectory: URL)

设置 Swift 应用指标将在其中查找数据源/连接器插件的目录。

SwiftMetrics.monitor() -> SwiftMonitor

创建一个 Swift 应用指标本地客户端实例，该实例连接到由“SwiftMetrics”指定的 Swift 应用指标代理。随后，可以使用它来获取环境数据并订阅由代理生成的数据。如果 Swift 应用指标代理尚未运行，则此函数将启动它。

SwiftMetrics.emitData<T: SMData( _: T)

允许您发出自定义数据，并将数据类型指定为字符串。传递到事件中的数据必须实现 SMData 协议。

SwiftMonitor.getEnvironmentData() -> [ String : String ]

请求一个字典对象，其中包含正在运行的应用程序的所有可用环境信息。如果在发出“initialized”事件之前调用，则它将包含不完整的数据或没有数据。

SwiftMonitor.on<T: SMData>((T) -> ())

如果您提供一个闭包，该闭包接受 预先提供的 API 结构 或您自己的实现 SMData 协议的自定义结构，并且不返回任何内容，那么当发出相关数据时，该闭包将运行。

SwiftMetricsKitura(swiftMetricsInstance: SwiftMetrics) (导入 SwiftMetricsKitura 时)

创建一个 SwiftMetricsKitura 实例，该实例将监视 Kitura HTTP 指标并通过指定的 SwiftMetrics 实例发出它们。

SwiftMetricsBluemix(swiftMetricsInstance: SwiftMetrics) (导入 SwiftMetricsBluemix 时)

创建一个 SwiftMetricsBluemix 实例，该实例会将指标发送到 Auto Scale service。

API 数据结构

以下所有结构都实现了 SMData 协议，以将它们标识为可供 SwiftMetrics 使用。

public protocol SMData {
}

CPU 数据结构

在获取 CPU 监视样本时发出。

public struct CPUData: SMData
- timeOfSample (Int) 自 epoch 以来，以毫秒为单位的系统时间，表示获取样本的时间。
- percentUsedByApplication (Float) Swift 应用程序本身使用的 CPU 百分比。这是一个介于 0.0 和 1.0 之间的值。
- percentUsedBySystem (Float) 整个系统使用的 CPU 百分比。这是一个介于 0.0 和 1.0 之间的值。

内存数据结构

在获取内存监视样本时发出。

public struct MemData: SMData
- timeOfSample (Int) 自 epoch 以来，以毫秒为单位的系统时间，表示获取样本的时间。
- totalRAMOnSystem (Int) 系统上可用的总 RAM 量（以字节为单位）。
- totalRAMUsed (Int) 系统上使用的 RAM 总量（以字节为单位）。
- totalRAMFree (Int) 系统上可用的空闲 RAM 总量（以字节为单位）。
- applicationAddressSpaceSize (Int) Swift 应用程序使用的内存地址空间（以字节为单位）。
- applicationPrivateSize (Int) Swift 应用程序使用的无法与其他进程共享的内存量（以字节为单位）。
- applicationRAMUsed (Int) Swift 应用程序使用的 RAM 量（以字节为单位）。

HTTP 数据结构（包含 SwiftMetricsKitura 时）

在获取 HTTP 监视样本时发出。

public struct HTTPData: SMData
- timeOfRequest (Int) 自 epoch 以来，以毫秒为单位的系统时间，表示发出请求的时间。
- url (String) 请求 URL。
- duration (Double) 请求花费的时间（以毫秒为单位）。
- statusCode (HTTPStatusCode) 请求的 HTTP 状态代码。
- requestMethod (String) 请求的方法 {GET SET}。

已初始化数据结构

在收到所有预期的环境样本时发出，表示 SwiftMonitor.getEnvironmentData() 可用一整套环境变量。

public struct InitData: SMData
- data ([String: String] 字典)，其中包含环境变量名:值对。内容因系统而异。

环境数据结构

在获取环境样本时发出。使用此数据获得的字典可能不代表一整套环境变量。

public struct EnvData: SMData
- data ([String: String] 字典)，其中包含环境变量名:值对。内容因系统而异。

延迟数据结构

在获取延迟样本时发出。

public struct LatencyData: SMData
- timeOfSample (Int) 自 epoch 以来，以毫秒为单位的系统时间，表示获取样本的时间。
- duration (Double) 样本在 dispatch 队列中等待执行的时间。

示例

有两个可用的示例：

commonSample 演示了如何使用 API 从常见数据类型获取数据。
emitSample 演示了自定义数据发送和收集的使用。

要使用其中任何一个，请导航到它们的目录并执行 swift build（在 macOS 上，执行 swift build -Xlinker -lc++）。

故障排除

请在下面找到一些可能的故障场景和相应的诊断步骤。故障排除信息的更新将在 SwiftMetrics wiki 上提供：故障排除。如果这些资源无法帮助您解决问题，您可以在 Swift 应用指标问题跟踪器上打开一个问题。

检查 Swift 应用指标是否已启动

默认情况下，当 Swift 应用指标启动时，将向控制台输出写入类似以下的消息：

[Fri Aug 21 09:36:58 2015] com.ibm.diagnostics.healthcenter.loader INFO: Swift Application Metrics 1.0.1-201508210934 (Agent Core 3.0.5.201508210934)

错误“Failed to open library .../libagentcore.so: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.15' not found”

此错误表明在加载模块的本机部分或其依赖库之一时出现问题。 libagentcore.so 依赖于特定（最低）版本的 C 运行时库，如果找不到该版本，则会导致此错误。

检查

您的系统已安装所需版本的 libstdc++。您可能需要在包管理器中安装或更新一个包。如果您的操作系统不提供此版本的包，您可能必须安装独立软件 - 请参阅您操作系统的文档或支持论坛。
如果您安装了合适的 libstdc++ 版本，请确保它位于系统库路径中，或者使用某种方法（例如在 Linux 上设置 LD_LIBRARY_PATH 环境变量）将该库添加到搜索路径。

源代码

Swift 的 Application Metrics 的源代码可在 Swiftmetrics 项目中找到。有关使用源代码的信息（从源代码安装、开发、贡献）可在 SwiftMetrics wiki 上找到。

许可证

本项目采用 Apache 2.0 开源许可证发布。

版本控制方案

本项目使用符合 SemVer 规范的 X.0.Z 版本号进行发布，其中 X 用于公共 API 的重大更改（如本文档所述），Z 用于错误修复以及提供新功能的公共 API 的非重大更改。

开发版本

本项目的非发布版本（例如在 github.com/RuntimeTools/SwiftMetrics 上）将使用符合 SemVer 规范的 X.0.Z-dev.B 版本号，其中 X.0.Z 是最后一个发布的版本，Z 递增，B 是一个整数。有关开发过程的更多信息，请访问 SwiftMetrics wiki：开发。

版本

2.6.0

发布历史

2.6.0 - 更新到最新的 graphMetrics 版本
2.5.1 - 修复编译警告
2.5.0 - 移除 SwiftyRequest 并支持 Kitura-NIO
2.4.2 - 移除 Swift 4.2 编译器警告
2.4.1 - 重构以移除 SwiftyJSON 依赖并进行小幅修复
2.4.0 - 新的 REST 接口
2.3.0 - 支持 Swift 4.1
2.2.1 - 小幅依赖版本更改
2.2.0 - SwiftMetrics 仪表板中的新摘要选项卡
2.1.0 - 移除 KituraRequest 依赖并切换到 SwiftyRequest
2.0.4 - 重新应用 Swift-cfenv 版本更改
2.0.3 - 提供崩溃修复，无需更改 Swift-cfenv 版本
2.0.2 - 修复部署到 IBM 云时发生的崩溃。
2.0.1 - 小幅修复。
2.0.0 - 依赖更新以使用 Kitura 2
1.2.5 - 小幅修复。
1.2.4 - Prometheus 支持，内存图复选框，URL 过滤 & 删除 Swift 3.0 支持。
1.2.3 - 依赖更新，图形大小调整和 Swift 4 支持。
1.2.2 - 小幅修复。
1.2.1 - 小幅修复。
1.2.0 - 改进测试。
1.1.0 - 添加 WSS 支持。
1.0.3 - Swift 3.1.1 支持（包括仪表板）。
1.0.2 - 初始 Swift 3.1 支持（SwiftMetricsDash 在 3.1 上无法正常工作）。
1.0.0 - 第一个 GA 版本。
0.0.12 - BlueMix AutoScaling 支持。
0.0.11 - BlueMix 支持。
0.0.10 - 添加 Kitura HTTP 收集源。
0.0.9 - 初始开发版本。