{"id":27996583,"url":"https://github.com/runtimetools/swiftmetrics","last_synced_at":"2025-06-28T06:35:34.244Z","repository":{"id":63920424,"uuid":"80021491","full_name":"RuntimeTools/SwiftMetrics","owner":"RuntimeTools","description":"Swift Application Metrics instruments the Swift runtime for performance monitoring, providing the monitoring data programatically via an API or visually with an Eclipse Client.","archived":false,"fork":false,"pushed_at":"2021-10-27T10:01:21.000Z","size":1023,"stargazers_count":157,"open_issues_count":22,"forks_count":50,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-24T16:22:40.926Z","etag":null,"topics":["application-metrics","debug","health-center-client","metric-collectors","metrics","metrics-gathering","monitoring","monitoring-server","performance-monitoring","performance-visualization","swift","swift-application-metrics","swiftmetrics"],"latest_commit_sha":null,"homepage":"https://developer.ibm.com/swift/monitoring-diagnostics/application-metrics-for-swift/","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RuntimeTools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-01-25T14:23:01.000Z","updated_at":"2025-02-10T08:14:28.000Z","dependencies_parsed_at":"2022-11-29T10:45:09.585Z","dependency_job_id":null,"html_url":"https://github.com/RuntimeTools/SwiftMetrics","commit_stats":null,"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeTools%2FSwiftMetrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeTools%2FSwiftMetrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeTools%2FSwiftMetrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RuntimeTools%2FSwiftMetrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RuntimeTools","download_url":"https://codeload.github.com/RuntimeTools/SwiftMetrics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253154626,"owners_count":21862561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-metrics","debug","health-center-client","metric-collectors","metrics","metrics-gathering","monitoring","monitoring-server","performance-monitoring","performance-visualization","swift","swift-application-metrics","swiftmetrics"],"created_at":"2025-05-08T21:46:35.667Z","updated_at":"2025-05-08T21:46:36.480Z","avatar_url":"https://github.com/RuntimeTools.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/RuntimeTools/SwiftMetrics.svg?branch=master)](https://travis-ci.org/RuntimeTools/SwiftMetrics)\r\n[![codebeat badge](https://codebeat.co/badges/ba585c17-fcf2-4c84-9e68-c2eb0a7d12b2)](https://codebeat.co/projects/github-com-runtimetools-swiftmetrics-master)\r\n[![codecov.io](https://codecov.io/github/RuntimeTools/SwiftMetrics/coverage.svg?branch=master)](https://codecov.io/github/RuntimeTools/SwiftMetrics?branch=master)\r\n![macOS](https://img.shields.io/badge/os-macOS-green.svg?style=flat)\r\n![Linux](https://img.shields.io/badge/os-linux-green.svg?style=flat)\r\n![Apache 2](https://img.shields.io/badge/license-Apache2-blue.svg?style=flat)\r\n\u0026nbsp;[![Slack Status](http://swift-at-ibm-slack.mybluemix.net/badge.svg)](http://swift-at-ibm-slack.mybluemix.net/)\r\n[![Homepage](https://img.shields.io/badge/homepage-Application%20Metrics%20for%20Swift-blue.svg)](https://developer.ibm.com/swift/monitoring-diagnostics/application-metrics-for-swift)\r\n\r\n# Application Metrics for Swift\r\n\r\n[Application Metrics for Swift](https://developer.ibm.com/swift/monitoring-diagnostics/application-metrics-for-swift) instruments the Swift runtime for performance monitoring, providing the monitoring data programatically via an API or visually with its built-in dashboard.\r\n\r\nApplication Metrics for Swift provides the following built-in data collection sources:\r\n\r\n Source             | Description\r\n:-------------------|:-------------------------------------------\r\n Environment        | Machine and runtime environment information\r\n CPU                | Process and system CPU\r\n Memory             | Process and system memory usage\r\n Latency            | Dispatch Queue latency\r\n\r\n SwiftMetricsKitura adds the additional collection source:\r\n\r\n Source             | Description\r\n:-------------------|:-------------------------------------------\r\n HTTP               | HTTP metric information\r\n\r\n\r\n## Getting Started\r\n### Prerequisites\r\n\r\nThe Application Metrics for Swift agent supports the following runtime environments:\r\n\r\n* **Swift v4.2 GA** on:\r\n  * 64-bit runtime on Linux (Ubuntu 14.04, 16.04)\r\n  * 64-bit runtime on macOS (x64)\r\n* **Swift v4.1 GA** on:\r\n  * 64-bit runtime on Linux (Ubuntu 14.04, 16.04)\r\n  * 64-bit runtime on macOS (x64)\r\n* **Swift v4 GA** on:\r\n  * 64-bit runtime on Linux (Ubuntu 14.04, 16.04)\r\n  * 64-bit runtime on macOS (x64)\r\n* **Swift v3.1.1 GA** using SwiftMetrics version 1.2.5 on:\r\n  * 64-bit runtime on Linux (Ubuntu 14.04, 15.10)\r\n  * 64-bit runtime on macOS (x64)\r\n\r\n\u003ca name=\"install\"\u003e\u003c/a\u003e\r\n### Installation\r\nApplication Metrics for Swift can be installed by adding a dependency into your Package.swift file and updating your targets to include SwiftMetrics as a dependency:\r\n\r\n```swift\r\n   dependencies: [\r\n      .package(url: \"https://github.com/RuntimeTools/SwiftMetrics.git\", from: \"2.4.0\")\r\n   ]\r\n   ...\r\n   targets: [\r\n      .target(name: \"MyApp\", dependencies: [\"SwiftMetrics\"], path: \"Sources\")]\r\n```\r\n\r\nSwift Package manager will automatically clone the code required and build it during compilation of your program:\r\n  * Linux: `swift build`\r\n  * macOS: `swift build -Xlinker -lc++`\r\n\r\n\u003ca name=\"config\"\u003e\u003c/a\u003e\r\n### Configuring Application Metrics for Swift\r\nOnce Application Metrics for Swift is added as a dependency to your Swift application, you should find a configuration file inside the `.build` folder, `.build/checkouts/SwiftMetrics.git--\u003cid\u003e/swiftmetrics.properties` (or the `Packages` directory for older versions of Swift, `Packages/SwiftMetrics-\u003cversion\u003e/swiftmetrics.properties`). This is used to configure connection options, logging and data source options.\r\n\r\nApplication Metrics for Swift will attempt to load `swiftmetrics.properties` from one of the following locations (in order):\r\n\r\n1. The current working directory.\r\n2. The `.build/checkouts/SwiftMetrics.git--\u003cid\u003e` directory (or `Packages/SwiftMetrics-\u003cversion\u003e` for older versions of Swift).\r\n\r\nPlease note that the default configuration has minimal logging enabled.\r\n\r\n## Running Application Metrics for Swift\r\n\u003ca name=\"run-local\"\u003e\u003c/a\u003e\r\n### Modifying your application\r\n\r\nTo load `SwiftMetrics` and get the base monitoring API, add the following to the start-up code for your application:\r\n```swift\r\nimport SwiftMetrics\r\n\r\nlet sm = try SwiftMetrics()\r\nlet monitoring = sm.monitor()\r\n```\r\n\r\nIf you would like to monitor Kitura HTTP data as well, then use the following instead:\r\n```swift\r\nimport SwiftMetrics\r\nimport SwiftMetricsKitura\r\n\r\nlet sm = try SwiftMetrics()\r\nSwiftMetricsKitura(swiftMetricsInstance: sm)\r\nlet monitoring = sm.monitor()\r\n```\r\n\r\n### Application Metrics for Swift Dashboard\r\n\r\nTo use the built in dashboard, you add the following code to your application\r\n```swift\r\nimport SwiftMetrics\r\nimport SwiftMetricsDash\r\n\r\n// Enable SwiftMetrics Monitoring\r\nlet sm = try SwiftMetrics()   \r\n\r\n// Pass SwiftMetrics to the dashboard for visualising\r\nlet smd = try SwiftMetricsDash(swiftMetricsInstance : sm)  \r\n```\r\n\r\nBy default, SwiftMetricsDash will start its own Kitura server and serve the page up under `http://\u003chostname\u003e:\u003cport\u003e/swiftmetrics-dash`\r\n\r\nThe port being used is logged to the console when your application starts:\r\n\r\n * SwiftMetricsDash : Starting on port 8080\r\n\r\n### Prometheus Support\r\n\r\nTo use SwiftMetrics to provide a [Prometheus](https://prometheus.io/) endpoint, you add the following code to your application\r\n```swift\r\nimport SwiftMetrics\r\nimport SwiftMetricsPrometheus\r\n\r\n// Enable SwiftMetrics Monitoring\r\nlet sm = try SwiftMetrics()   \r\n\r\n// Pass SwiftMetrics to SwiftMetricsPrometheus\r\nlet smp = try SwiftMetricsPrometheus(swiftMetricsInstance : sm)\r\n```\r\n\r\nBy default, SwiftMetricsPrometheus will provide the Prometheus endpoint under `http://\u003chostname\u003e:\u003cport\u003e/metrics`\r\n\r\nThe port being used is logged to the console when your application starts:\r\n\r\n * SwiftMetricsPrometheus : Starting on port 8080\r\n\r\n### Application Metrics for Swift Agent\r\n\r\nSwiftMetrics() returns the Application Metrics for Swift Agent - this runs parallel to your code and receives and emits data about your application to any connected clients. The `sm.monitor()` call returns a Application Metrics for Swift Local Client, connected to the Agent `sm` over a local connection.\r\n\r\nYou can then use the monitoring object to register callbacks and request information about the application:\r\n```swift\r\nmonitoring.on({ (env: InitData) in\r\n   for (key, value) in env {\r\n      print(\"\\(key): \\(value)\\n\")\r\n   }\r\n})\r\n\r\nfunc processCPU(cpu: CPUData) {\r\n   print(\"\\nThis is a custom CPU event response.\\n cpu.timeOfSample = \\(cpu.timeOfSample),\\n cpu.percentUsedByApplication = \\(cpu.percentUsedByApplication),\\n cpu.percentUsedBySystem = \\(cpu.percentUsedBySystem).\\n\")\r\n}\r\n\r\nmonitoring.on(processCPU)\r\n```\r\n\r\nIn order to monitor your own custom data, you need to implement a struct that implements the base SwiftMetrics data protocol, SMData. This has no required fields so you can put in just the data you're interested in.\r\n```swift\r\nprivate struct SnoozeData: SMData {\r\n   let cycleCount: Int\r\n}\r\n\r\nprivate func snoozeMessage(data: SnoozeData) {\r\n   print(\"\\nAlarm has been ignored for \\(data.cycleCount) seconds!\\n\")\r\n}\r\n\r\nmonitoring.on(snoozeMessage)\r\n\r\nsm.emitData(SnoozeData(cycleCount: 40))\r\n\r\n//prints \"Alarm has been ignored for 40 seconds!\"\r\n```\r\n\r\n\u003ca name=\"api-doc\"\u003e\u003c/a\u003e\r\n## API Documentation\r\n\r\n### SwiftMetrics.start()\r\nStarts the Application Metrics for Swift Agent. If the agent is already running this function does nothing.\r\n\r\n### SwiftMetrics.stop()\r\nStops the Application Metrics for Swift Agent. If the agent is not running this function does nothing.\r\n\r\n### SwiftMetrics.setPluginSearch(toDirectory: URL)\r\nSets the directory that Application Metrics for Swift will look in for data source / connector plugins.\r\n\r\n### SwiftMetrics.monitor() -\u003e SwiftMonitor\r\nCreates a Application Metrics for Swift Local Client instance, connected to the Application Metrics for Swift Agent specified by 'SwiftMetrics'. This can subsequently be used to get environment data and subscribe to data generated by the Agent.. This function will start the Application Metrics for Swift Agent if it is not already running.\r\n\r\n### SwiftMetrics.emitData\u003cT: SMData( _: T)\r\nAllows you to emit custom Data specifying the type of Data as a string. Data to pass into the event must implement the SMData protocol.\r\n\r\n### SwiftMonitor.getEnvironmentData() -\u003e [ String : String ]\r\nRequests a Dictionary object containing all of the available environment information for the running application. If called before the 'initialized' event has been emitted, this will contain either incomplete data or no data.\r\n\r\n### SwiftMonitor.on\u003cT: SMData\u003e((T) -\u003e ())\r\nIf you supply a closure that takes either a *[pre-supplied API struct](#api-structs)* or your own custom struct that implements the SMData protocol,  and returns nothing, then that closure will run when the data in question is emitted.\r\n\r\n### SwiftMetricsKitura(swiftMetricsInstance: SwiftMetrics) (when importing SwiftMetricsKitura)\r\nCreates a SwiftMetricsKitura instance, which will monitor Kitura HTTP metrics and emit them via the SwiftMetrics instance specified.\r\n\r\n### SwiftMetricsBluemix(swiftMetricsInstance: SwiftMetrics) (when importing SwiftMetricsBluemix)\r\nCreates a SwiftMetricsBluemix instance, which will send metrics to the [Auto Scale service][4]\r\n\r\n\u003ca name=\"api-structs\"\u003e\u003c/a\u003e\r\n## API Data Structures\r\n\r\nAll of the following structures implement the SMData protocol to identify them as available to be used by SwiftMetrics.\r\n```swift\r\npublic protocol SMData {\r\n}\r\n```\r\n\r\n### CPU data structure\r\nEmitted when a CPU monitoring sample is taken.\r\n* `public struct CPUData: SMData`\r\n    * `timeOfSample` (Int) the system time in milliseconds since epoch when the sample was taken.\r\n    * `percentUsedByApplication` (Float) the percentage of CPU used by the Swift application itself. This is a value between 0.0 and 1.0.\r\n    * `percentUsedBySystem` (Float) the percentage of CPU used by the system as a whole. This is a value between 0.0 and 1.0.\r\n\r\n### Memory data structure\r\nEmitted when a memory monitoring sample is taken.\r\n* `public struct MemData: SMData`\r\n    * `timeOfSample` (Int) the system time in milliseconds since epoch when the sample was taken.\r\n    * `totalRAMOnSystem` (Int) the total amount of RAM available on the system in bytes.\r\n    * `totalRAMUsed` (Int) the total amount of RAM in use on the system in bytes.\r\n    * `totalRAMFree` (Int) the total amount of free RAM available on the system in bytes.\r\n    * `applicationAddressSpaceSize` (Int) the memory address space used by the Swift application in bytes.\r\n    * `applicationPrivateSize` (Int) the amount of memory used by the Swift application that cannot be shared with other processes, in bytes.\r\n    * `applicationRAMUsed` (Int) the amount of RAM used by the Swift application in bytes.\r\n\r\n### HTTP data structure (when including SwiftMetricsKitura)\r\nEmitted when an HTTP monitoring sample is taken.\r\n* `public struct HTTPData: SMData`\r\n    * `timeOfRequest` (Int) the system time in milliseconds since epoch when the request was made.\r\n    * `url` (String) the request url.\r\n    * `duration` (Double) the duration in milliseconds that the request took.\r\n    * `statusCode` (HTTPStatusCode) the HTTP status code of the request.\r\n    * `requestMethod` (String) the method {GET SET} of the request.\r\n\r\n### Initialized data structure\r\nEmitted when all expected environment samples have been received, signalling a complete set of environment variables is available for SwiftMonitor.getEnvironmentData().\r\n* `public struct InitData: SMData`\r\n    * `data` ([String: String] Dictionary) of environment variable name:value pairs. The contents vary depending on system.\r\n\r\n### Environment data structure\r\nEmitted when an environment sample is taken. The Dictionary obtained with this data may not represent the complete set of environment variables.\r\n* `public struct EnvData: SMData`\r\n    * `data` ([String: String] Dictionary) of environment variable name:value pairs. The contents vary depending on system.\r\n\r\n### Latency data structure\r\nEmitted when a Latency sample is taken.\r\n* `public struct LatencyData: SMData`\r\n    * `timeOfSample` (Int) the system time in milliseconds since epoch when the sample was taken.\r\n    * `duration` (Double) the duration the sample waited in the dispatch queue to be executed.\r\n\r\n## Samples\r\n\r\nThere are two samples available:\r\n* `commonSample` demonstrates how to get data from the common data types, using the API.\r\n* `emitSample` demonstrates the use of Custom Data emission and collection.\r\n\r\nTo use either, navigate to their directory and issue `swift build` (on macOS, `swift build -Xlinker -lc++`)\r\n\r\n## Troubleshooting\r\nFind below some possible problem scenarios and corresponding diagnostic steps. Updates to troubleshooting information will be made available on the [SwiftMetrics wiki][1]: [Troubleshooting](https://github.com/RuntimeTools/SwiftMetrics/wiki/Troubleshooting). If these resources do not help you resolve the issue, you can open an issue on the Application Metrics for Swift [issue tracker][2].\r\n\r\n### Checking Application Metrics for Swift has started\r\nBy default, a message similar to the following will be written to console output when Application Metrics for Swift starts:\r\n\r\n`[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)`\r\n\r\n### Error \"Failed to open library .../libagentcore.so: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.15' not found\"\r\nThis error indicates there was a problem while loading the native part of the module or one of its dependent libraries. `libagentcore.so` depends on a particular (minimum) version of the C runtime library and if it cannot be found this error is the result.\r\n\r\nCheck:\r\n\r\n* Your system has the required version of `libstdc++` installed. You may need to install or update a package in your package manager. If your OS does not supply a package at this version, you may have to install standalone software - consult the documentation or support forums for your OS.\r\n* If you have an appropriate version of `libstdc++`installed, ensure it is on the system library path, or use a method (such as setting `LD_LIBRARY_PATH` environment variable on Linux) to add the library to the search path.\r\n\r\n## Source code\r\nThe source code for Application Metrics for Swift is available in the [Swiftmetrics project][3]. Information on working with the source code -- installing from source, developing, contributing -- is available on the [SwiftMetrics wiki][1].\r\n\r\n## License\r\nThis project is released under an Apache 2.0 open source license.  \r\n\r\n## Versioning scheme\r\nThis project uses a semver-parsable X.0.Z version number for releases, where X is incremented for breaking changes to the public API described in this document and Z is incremented for bug fixes **and** for non-breaking changes to the public API that provide new function.\r\n\r\n### Development versions\r\nNon-release versions of this project (for example on github.com/RuntimeTools/SwiftMetrics) will use semver-parsable X.0.Z-dev.B version numbers, where X.0.Z is the last release with Z incremented and B is an integer. For further information on the development process go to the  [SwiftMetrics wiki][1]: [Developing](https://github.com/RuntimeTools/SwiftMetrics/wiki/Developing).\r\n\r\n## Version\r\n2.6.0\r\n\r\n## Release History\r\n`2.6.0` - Update to latest graphMetrics version  \r\n`2.5.1` - Fix compilation warnings  \r\n`2.5.0` - Removal of `SwiftyRequest` and support for Kitura-NIO  \r\n`2.4.2` - Removal of Swift 4.2 compiler warnings  \r\n`2.4.1` - Refactoring to remove SwiftyJSON dependency and minor fixes  \r\n`2.4.0` - New REST interface  \r\n`2.3.0` - Support Swift 4.1  \r\n`2.2.1` - Minor dependency version change  \r\n`2.2.0` - New summary tab in SwiftMetrics dashboard  \r\n`2.1.0` - Remove KituraRequest dependency and switch to SwiftyRequest  \r\n`2.0.4` - Reapply Swift-cfenv version change  \r\n`2.0.3` - Provide crash fix without Swift-cfenv version change  \r\n`2.0.2` - Fix crash when deployed to IBM cloud.  \r\n`2.0.1` - Minor fixes.  \r\n`2.0.0` - Dependency update to use Kitura 2  \r\n`1.2.5` - Minor fixes.  \r\n`1.2.4` - Prometheus support, memory graph checkboxes, URL filtering \u0026 drop Swift 3.0 support.  \r\n`1.2.3` - Dependency updates, graph resizing and Swift 4 support.  \r\n`1.2.2` - Minor fixes.  \r\n`1.2.1` - Minor fixes.  \r\n`1.2.0` - Improvements to testing.  \r\n`1.1.0` - Add WSS support.  \r\n`1.0.3` - Swift 3.1.1 support (including dashboard).  \r\n`1.0.2` - Initial Swift 3.1 support (SwiftMetricsDash not working on 3.1).  \r\n`1.0.0` - First GA release.  \r\n`0.0.12` - BlueMix AutoScaling support.  \r\n`0.0.11` - BlueMix support.  \r\n`0.0.10` - Addition of Kitura HTTP collection source.  \r\n`0.0.9` - Initial development release.  \r\n\r\n\r\n[1]: https://github.com/RuntimeTools/SwiftMetrics/wiki\r\n[2]: https://github.com/RuntimeTools/SwiftMetrics/issues\r\n[3]: https://github.com/RuntimeTools/SwiftMetrics\r\n[4]: https://www.ibm.com/cloud-computing/bluemix/auto-scale\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntimetools%2Fswiftmetrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruntimetools%2Fswiftmetrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntimetools%2Fswiftmetrics/lists"}