### Start Docker Services Source: https://xcmetrics.io/docs/run-the-backend-locally.html Start the Redis and Postgres instances using docker-compose. Remember to stop them later using 'docker-compose stop'. ```bash docker-compose up -d ``` -------------------------------- ### Start Backend with Docker Compose Source: https://xcmetrics.io/docs/run-the-backend-locally.html Use this command to start the Postgres database, Redis, and the XCMetrics backend using the provided Docker compose file. The backend will be available on port 8080. ```bash docker-compose -f docker-compose-local.yml up ``` -------------------------------- ### configure(_:) Source: https://xcmetrics.io/docs/Other%20Functions.html Configures the application. This is a global function available for application setup. ```APIDOC ## configure(_:) ### Description Configures the application. This is a global function available for application setup. ### Method `public func configure(_ app: Application) throws` ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response None #### Response Example None ``` -------------------------------- ### Start Backend with Swift Source: https://xcmetrics.io/docs/run-the-backend-locally.html Run the XCMetrics backend application from the command line using Swift. Ensure Redis and Postgresql are running. ```bash swift run XCMetricsBackend ``` -------------------------------- ### Build Response Structure Source: https://xcmetrics.io/docs/Structs/BuildController.html Example structure of a paginated response containing build metadata and a list of build items. ```json { "metadata": { "per": 10, "total": 100, "page": 2 }, "items": [ { "userid": "tim", "warningCount": 3, "duration": 1.10, "isCi": false, "startTimestamp": "2020-11-02T16:36:22Z", "startTimestampMicroseconds": 1604334982.5824749, "category": "noop", "endTimestampMicroseconds": 1604334993.6019359, "tag": "", "compilationEndTimestamp": "2020-11-02T16:36:22Z", "compilationDuration": 0, "projectName": "MyProject", "compilationEndTimestampMicroseconds": 1604334982.5824749, "errorCount": 0, "buildStatus": "succeeded", "day": "2020-11-02T00:00:00Z", "id": "MyMac_D682E30D-AF89-4712-A78E-85DC0AAB83C8_1", "schema": "App", "compiledCount": 0, "endTimestamp": "2020-11-02T16:36:33Z", "userid256": "c28b6fd9a49bd8c74767501a114784d327336f3ff861873341b5b64900125463", "machineName": "MyMac", "wasSuspended": false }, ... ] } ``` -------------------------------- ### Get Build Information Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves detailed information about a specific build, including build data, Xcode version, and associated targets. Use this endpoint to get a comprehensive overview of a past build. ```swift public func list(req: Request) throws -> EventLoopFuture> ``` ```json { "build": { "userid": "tim", "warningCount": 3, "duration": 1.4, "startTimestamp": "2020-11-02T16:38:40Z", "isCi": false, "startTimestampMicroseconds": 1604335120.279242, "category": "incremental", "endTimestampMicroseconds": 1604335135.242979, "day": "2020-11-02T00:00:00Z", "compilationEndTimestamp": "2020-11-02T16:38:55Z", "compilationDuration": 1.48, "projectName": "MyProject", "compilationEndTimestampMicroseconds": 1604335135.128335, "buildStatus": "failed", "id": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "tag": "", "errorCount": 1, "schema": "App", "compiledCount": 86, "endTimestamp": "2020-11-02T16:38:55Z", "userid256": "c28b6fd9a49bd8c74767501a114784d327336f3ff861873341b5b64900125463", "machineName": "MyMac", "wasSuspended": false }, "xcode": { "buildNumber": "12A7209", "id": "6354C87F-0ADC-4354-929C-02EBE545E099", "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "day": "2020-11-02T00:00:00Z", "version": "1200" }, "targets": [ { "id": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1992", "category": "noop", "startTimestamp": "2020-11-02T10:59:09Z", "compilationEndTimestampMicroseconds": 1604314749.2909288, "endTimestampMicroseconds": 1604314982.298002, "endTimestamp": "2020-11-02T11:03:02Z", "fetchedFromCache": true, "errorCount": 0, "day": "2020-11-02T00:00:00Z", "warningCount": 0, "compilationEndTimestamp": "2020-11-02T10:59:09Z", "compilationDuration": 0, "compiledCount": 0, "duration": 0.000233007, "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "name": "Model", "startTimestampMicroseconds": 1604314749.2909288 }, ... ] } ``` -------------------------------- ### Run Database Migrations with Swift Source: https://xcmetrics.io/docs/run-the-backend-locally.html Execute database migrations to create necessary tables for the project. This is typically done the first time you start the backend or after table schema changes. ```bash swift run XCMetricsBackend migrate ``` -------------------------------- ### Get Daily Build Time Source: https://xcmetrics.io/docs/Protocols/StatisticsRepository.html Calculates and returns build time information for a given day. Use for specific day build performance. ```swift func getBuildTime(day: Date, using eventLoop: EventLoop) -> EventLoopFuture ``` -------------------------------- ### Get Build Warnings Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves the list of warnings associated with a specific build. ```APIDOC ## GET /v1/build/warning/ ### Description Retrieves a list of compilation warnings that occurred during a specific build. ### Method GET ### Endpoint /v1/build/warning/ ### Parameters #### Path Parameters - **buildId** (string) - Required - Build's identifier ### Response #### Success Response (200) - **detail** (string) - Detailed warning message. - **characterRangeEnd** (integer) - The end character index of the warning in the source file. - **documentURL** (string) - The URL of the source file where the warning occurred. - **endingColumn** (integer) - The ending column number in the source file where the warning occurred. - **id** (string) - Unique identifier for the warning. - **parentIdentifier** (string) - Identifier of the parent build step. - **day** (string) - The date the warning occurred. - **type** (string) - The type of warning (e.g., deprecatedWarning). - **title** (string) - A summary title of the warning. - **endingLine** (integer) - The ending line number in the source file where the warning occurred. - **severity** (integer) - The severity level of the warning. - **startingLine** (integer) - The starting line number in the source file where the warning occurred. - **parentType** (string) - The type of the parent build step. - **clangFlag** (string) - The clang flag associated with the warning. - **startingColumn** (integer) - The starting column number in the source file where the warning occurred. - **buildIdentifier** (string) - The identifier of the build. - **characterRangeStart** (integer) - The start character index of the warning in the source file. ### Response Example ```json [ { "detail": null, "characterRangeEnd": 9817, "documentURL": "file:\/\/\/Users\/\/myproject\/Sources\/MyViewController.m", "endingColumn": 22, "id": "5F2011AC-F87F-4EDC-BBC6-2BBA3D789EB3", "parentIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1845", "day": "2020-11-02T00:00:00Z", "type": "deprecatedWarning", "title": "'dimsBackgroundDuringPresentation' is deprecated: first deprecated in iOS 12.0", "endingLine": 235, "severity": 1, "startingLine": 235, "parentType": "step", "clangFlag": "[-Wdeprecated-declarations]", "startingColumn": 22, "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "characterRangeStart": 0 } ] ``` ``` -------------------------------- ### Get Build Information Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves the most relevant information of a Build, including Build data, Xcode version, and a list of Targets that were built. ```APIDOC ## GET /v1/build/ ### Description Retrieves detailed information about a specific build, including its status, timestamps, associated Xcode version, and a list of targets that were part of the build process. ### Method GET ### Endpoint /v1/build/ ### Parameters #### Path Parameters - **buildId** (string) - Required - Build's identifier ### Response #### Success Response (200) - **build** (object) - Detailed build information. - **xcode** (object) - Information about the Xcode version used for the build. - **targets** (array) - A list of targets that were built. ### Response Example ```json { "build": { "userid": "tim", "warningCount": 3, "duration": 1.4, "startTimestamp": "2020-11-02T16:38:40Z", "isCi": false, "startTimestampMicroseconds": 1604335120.279242, "category": "incremental", "endTimestampMicroseconds": 1604335135.242979, "day": "2020-11-02T00:00:00Z", "compilationEndTimestamp": "2020-11-02T16:38:55Z", "compilationDuration": 1.48, "projectName": "MyProject", "compilationEndTimestampMicroseconds": 1604335135.128335, "buildStatus": "failed", "id": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "tag": "", "errorCount": 1, "schema": "App", "compiledCount": 86, "endTimestamp": "2020-11-02T16:38:55Z", "userid256": "c28b6fd9a49bd8c74767501a114784d327336f3ff861873341b5b64900125463", "machineName": "MyMac", "wasSuspended": false }, "xcode": { "buildNumber": "12A7209", "id": "6354C87F-0ADC-4354-929C-02EBE545E099", "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "day": "2020-11-02T00:00:00Z", "version": "1200" }, "targets": [ { "id": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1992", "category": "noop", "startTimestamp": "2020-11-02T10:59:09Z", "compilationEndTimestampMicroseconds": 1604314749.2909288, "endTimestampMicroseconds": 1604314982.298002, "endTimestamp": "2020-11-02T11:03:02Z", "fetchedFromCache": true, "errorCount": 0, "day": "2020-11-02T00:00:00Z", "warningCount": 0, "compilationEndTimestamp": "2020-11-02T10:59:09Z", "compilationDuration": 0, "compiledCount": 0, "duration": 0.000233007, "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "name": "Model", "startTimestampMicroseconds": 1604314749.2909288 } ] } ``` ``` -------------------------------- ### Get Target Steps Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves the list of steps performed during the build of a specific target. Requires the day and target ID. ```APIDOC ## GET /v1/build/step/:day/:targetId ### Description Endpoint that returns the list of `Step`s that were done to build a Target. ### Method GET ### Endpoint /v1/build/step/:day/:targetId ### Parameters #### Path Parameters - **day** (string) - Required - `Target`‘s day as String in UTC. example: `20210129` - **targetId** (string) - Required - `Target`‘s id. ### Response #### Success Response (200) - **Array of step objects**, each containing details about a build step. ### Response Example [ { "id": "ash22j3sdba1f0654c3f9e9a_6561690B-DFE4-4EE8-ABEE-99E4D3325E7B_16", "startTimestamp": "2021-01-29T08:11:41Z", "endTimestamp": "2021-01-29T08:11:41Z", "errorCount": 0, "endTimestampMicroseconds": 1611907901.256928, "fetchedFromCache": false, "targetIdentifier": "ecba60d222f04c51dba1f0654c3f9e9a_6561690B-DFE8-4EE8-ABEE-99E4D3325E7B_15", "day": "2021-01-29T00:00:00Z", "type": "other", "title": "Create directory SPTAuthAccountsTests.xctest", "warningCount": 0, "signature": "MkDir \/Users\/\/my_project\/build\/DerivedData\/Build\/Products\/Debug-iphonesimulator\/MyProjectTests.xctest", "architecture": "", "duration": 2.3, "documentURL": "", "buildIdentifier": "ash22j3sdba1f0654c3f9e9a_6561690B-DFE4-4EE8-ABEE-99E4D3325E7B_1", "startTimestampMicroseconds": 1611907901.255825 }, ... ] ``` -------------------------------- ### Get Project List Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves a list of all projects that have builds in the database. This can be used to filter builds by project. ```APIDOC ## GET /v1/build/project ### Description Endpoint that returns the list of projects from which there are `Build` on the database. Useful if you want the list to filter the build per project using the endpoint `/v1/build/list`. ### Method GET ### Endpoint /v1/build/project ### Response #### Success Response (200) - **Array of strings**, where each string is a project name. ### Response Example [ "Project1", "MyProject" ] ``` -------------------------------- ### Get Build Errors Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves the list of errors associated with a specific build. ```APIDOC ## GET /v1/build/error/ ### Description Retrieves a list of compilation errors that occurred during a specific build. ### Method GET ### Endpoint /v1/build/error/ ### Parameters #### Path Parameters - **buildId** (string) - Required - Build's identifier ### Response #### Success Response (200) - **detail** (string) - Detailed error message. - **characterRangeEnd** (integer) - The end character index of the error in the source file. - **id** (string) - Unique identifier for the error. - **endingColumn** (integer) - The ending column number in the source file where the error occurred. - **parentIdentifier** (string) - Identifier of the parent build step. - **day** (string) - The date the error occurred. - **type** (string) - The type of error (e.g., clangError). - **title** (string) - A summary title of the error. - **endingLine** (integer) - The ending line number in the source file where the error occurred. - **severity** (integer) - The severity level of the error. - **startingLine** (integer) - The starting line number in the source file where the error occurred. - **parentType** (string) - The type of the parent build step. - **buildIdentifier** (string) - The identifier of the build. - **startingColumn** (integer) - The starting column number in the source file where the error occurred. - **characterRangeStart** (integer) - The start character index of the error in the source file. - **documentURL** (string) - The URL of the source file where the error occurred. ### Response Example ```json [ { "detail": "\/Users\/\/myproject\/Sources\/MyClass.m:241:97:\/\/ \/ error: instance method 'fetch' not found ; did you mean 'fetchIt'?\r\n myclass:[self.myService fetch]\r ^~~~~~~~~~~~~~\r fetch\r 1 error generated.\r", "characterRangeEnd": 13815, "id": "3E6EF185-6AC1-4E95-87E8-E305F41916E9", "endingColumn": 97, "parentIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_8860", "day": "2020-11-02T00:00:00Z", "type": "clangError", "title": "Instance method 'fetch' not found ; did you mean 'fetchIt'?", "endingLine": 241, "severity": 2, "startingLine": 241, "parentType": "step", "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "startingColumn": 97, "characterRangeStart": 0, "documentURL": "file:\/\/\/Users\/\/myproject\/Sources\/MyClass.m" } ] ``` ``` -------------------------------- ### Get Build Times Source: https://xcmetrics.io/docs/Structs/StatisticsController.html Retrieves a list of daily build times, including percentile build durations and total build time for a specified number of past days. ```APIDOC ## GET /v1/statistics/build/time ### Description Endpoint that returns a list of `DayBuildTime` which includes the build times for a number of procentiles of the builds and the total build time for each day, in seconds. The `durationPX` fields indicate that X % of the builds of the a day had a duration less or equal to the value. ### Method GET ### Endpoint /v1/statistics/build/time ### Parameters #### Query Parameters - **days** (integer) - Required - How many days to include in the past, starting from the current date ### Response #### Success Response (200) - **id** (string) - The date of the statistics. - **durationP50** (number) - The duration in seconds for which 50% of the builds were completed. - **durationP95** (number) - The duration in seconds for which 95% of the builds were completed. - **totalDuration** (number) - The total build duration in seconds for the day. ### Response Example ```json [ { "id": "2021-07-26", "durationP50": 18473.21, "durationP95": 54431313.32, "totalDuration": 10983982398.549 }, ... ] ``` ``` -------------------------------- ### GET /v1/build Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves a paginated list of builds, sorted by date in descending order. Supports pagination parameters for controlling the number of results per page and the page number. ```APIDOC ## GET /v1/build ### Description Retrieves a paginated list of `Build` objects, sorted by date from most recent to least recent. Supports optional query parameters for pagination. ### Method GET ### Endpoint /v1/build ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number to fetch. Defaults to `1`. - **per** (integer) - Optional - Number of items to fetch per page. Defaults to `10`. ### Response #### Success Response (200) - **metadata** (object) - Contains pagination information. - **per** (integer) - Number of items per page. - **total** (integer) - Total number of items available. - **page** (integer) - Current page number. - **items** (array) - An array of `Build` objects. - **userid** (string) - **warningCount** (integer) - **duration** (number) - **isCi** (boolean) - **startTimestamp** (string) - **startTimestampMicroseconds** (number) - **category** (string) - **endTimestampMicroseconds** (number) - **tag** (string) - **compilationEndTimestamp** (string) - **compilationDuration** (number) - **projectName** (string) - **compilationEndTimestampMicroseconds** (number) - **errorCount** (integer) - **buildStatus** (string) - **day** (string) - **id** (string) - **schema** (string) - **compiledCount** (integer) - **endTimestamp** (string) - **userid256** (string) - **machineName** (string) - **wasSuspended** (boolean) ### Response Example { "metadata": { "per": 10, "total": 100, "page": 2 }, "items": [ { "userid": "tim", "warningCount": 3, "duration": 1.10, "isCi": false, "startTimestamp": "2020-11-02T16:36:22Z", "startTimestampMicroseconds": 1604334982.5824749, "category": "noop", "endTimestampMicroseconds": 1604334993.6019359, "tag": "", "compilationEndTimestamp": "2020-11-02T16:36:22Z", "compilationDuration": 0, "projectName": "MyProject", "compilationEndTimestampMicroseconds": 1604334982.5824749, "errorCount": 0, "buildStatus": "succeeded", "day": "2020-11-02T00:00:00Z", "id": "MyMac_D682E30D-AF89-4712-A78E-85DC0AAB83C8_1", "schema": "App", "compiledCount": 0, "endTimestamp": "2020-11-02T16:36:33Z", "userid256": "c28b6fd9a49bd8c74767501a114784d327336f3ff861873341b5b64900125463", "machineName": "MyMac", "wasSuspended": false } ] } ``` -------------------------------- ### Get Build Warnings Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves a list of compilation warnings for a specific build. Use this endpoint to identify potential issues or deprecated usage in your code. ```swift public func buildWarnings(req: Request) throws -> EventLoopFuture<[BuildError]> ``` ```json [ { "detail": null, "characterRangeEnd": 9817, "documentURL": "file:\/\/\/Users\/\/myproject\/Sources\/MyViewController.m", "endingColumn": 22, "id": "5F2011AC-F87F-4EDC-BBC6-2BBA3D789EB3", "parentIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1845", "day": "2020-11-02T00:00:00Z", "type": "deprecatedWarning", "title": "'dimsBackgroundDuringPresentation' is deprecated: first deprecated in iOS 12.0", "endingLine": 235, "severity": 1, "startingLine": 235, "parentType": "step", "clangFlag": "[-Wdeprecated-declarations]", "startingColumn": 22, "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "characterRangeStart": 0 } ] ``` -------------------------------- ### Get Build Host Information Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves the data of the host used in a specific build. Requires the build ID as a path parameter. ```APIDOC ## GET /v1/build/host/ ### Description Endpoint that returns the data of the host used in the given `Build`. ### Method GET ### Endpoint /v1/build/host/ ### Parameters #### Path Parameters - **buildId** (string) - Required - `Build`‘s identifier ### Response #### Success Response (200) - **id** (string) - **swapFreeMb** (number) - **hostOsFamily** (string) - **isVirtual** (boolean) - **uptimeSeconds** (number) - **hostModel** (string) - **hostOsVersion** (string) - **day** (string) - **cpuCount** (number) - **swapTotalMb** (number) - **hostOs** (string) - **hostArchitecture** (string) - **memoryTotalMb** (number) - **timezone** (string) - **cpuModel** (string) - **buildIdentifier** (string) - **memoryFreeMb** (number) - **cpuSpeedGhz** (number) ### Response Example { "id": "9DD5508D-4AD9-4C1C-AB7C-45BC2183EC51", "swapFreeMb": 1615.25, "hostOsFamily": "Darwin", "isVirtual": false, "uptimeSeconds": 1602055187, "hostModel": "MacBookPro14,2", "hostOsVersion": "10.15.7", "day": "2020-10-26T00:00:00Z", "cpuCount": 4, "swapTotalMb": 7168, "hostOs": "Mac OS X", "hostArchitecture": "x86_64", "memoryTotalMb": 16384, "timezone": "CET", "cpuModel": "Intel(R) Core(TM) i7-7567U CPU @ 3.50GHz", "buildIdentifier": "MyMac_1FE14870-EDF1-4E8C-B1AA-2C2DF484842B_1", "memoryFreeMb": 24.5234375, "cpuSpeedGhz": 3.5 } ``` -------------------------------- ### Filtered Build Response Structure Source: https://xcmetrics.io/docs/Structs/BuildController.html Example structure of a paginated response for filtered builds, including metadata and a list of matching build items. ```json { "metadata": { "per": 5, "total": 6, "page": 1 }, "items": [ { "userid": "tim", "warningCount": 3, "duration": 1.4963999999999999e-05, "startTimestamp": "2020-11-02T16:38:40Z", "isCi": false, "startTimestampMicroseconds": 1604335120.279242, "category": "incremental", "endTimestampMicroseconds": 1604335135.242979, "day": "2020-11-02T00:00:00Z", "compilationEndTimestamp": "2020-11-02T16:38:55Z", "compilationDuration": 1.4849e-05, "projectName": "MyProject", "compilationEndTimestampMicroseconds": 1604335135.128335, "buildStatus": "failed", "id": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "tag": "", "errorCount": 1, "schema": "MyProject", "compiledCount": 86, "endTimestamp": "2020-11-02T16:38:55Z", "userid256": "c28b6fd9a49bd8c74767501a114784d327336f3ff861873341b5b64900125463", "machineName": "MyMac", "wasSuspended": false }, ... ] } ``` -------------------------------- ### Check Deployed Services Source: https://xcmetrics.io/docs/how-to-deploy-backend.html Use `kubectl get services` to list all deployed services and their external IP addresses. Look for the `xcmetrics-server` service to find the LoadBalancer's external IP. ```bash kubectl get services ``` -------------------------------- ### Get GKE Cluster Credentials Source: https://xcmetrics.io/docs/how-to-deploy-backend.html Configure kubectl to connect to your newly created GKE cluster. Replace 'name-of-cluster' with the actual name of your cluster. ```bash gcloud container clusters get-credentials name-of-cluster ``` -------------------------------- ### Get Build Status Source: https://xcmetrics.io/docs/Structs/StatisticsController.html Retrieves a paginated list of build statuses to minimize payload size when many statuses are required. ```APIDOC ## GET /v1/statistics/build/status ### Description Endpoint that returns the paginated list of `BuildStatusResult` to minimize payload size when many statuses are required. ### Method GET ### Endpoint /v1/statistics/build/status ### Parameters #### Query Parameters - **page** (integer) - Optional - Page number to fetch. Default is `1` - **per** (integer) - Optional - Number of items to fetch per page. Default is `10` ### Response #### Success Response (200) - **metadata** (object) - Contains pagination information. - **per** (integer) - Number of items per page. - **total** (integer) - Total number of items available. - **page** (integer) - Current page number. - **items** (array) - List of build status results. - **id** (string) - The ID of the build status. - **buildStatus** (string) - The status of the build (e.g., 'succeeded'). ### Response Example ```json { "metadata": { "per": 10, "total": 100, "page": 2 }, "items": [ { "id": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "buildStatus": "succeeded" }, ... ] } ``` ``` -------------------------------- ### Get Daily Count Source: https://xcmetrics.io/docs/Protocols/StatisticsRepository.html Calculates and returns the number of builds and errors for a given day. Use for specific day statistics. ```swift func getCount(day: Date, using eventLoop: EventLoop) -> EventLoopFuture ``` -------------------------------- ### Build Metadata Retrieval Source: https://xcmetrics.io/docs/Structs/BuildController.html Swift function declaration for fetching build metadata. Use this to get metadata associated with a build, returned as a JSON object. ```swift public func metadata(req: Request) throws -> EventLoopFuture ``` -------------------------------- ### Get Build Errors Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves a list of compilation errors for a specific build. This endpoint is useful for diagnosing build failures by examining the detailed error messages. ```swift public func buildErrors(req: Request) throws -> EventLoopFuture<[BuildError]> ``` ```json [ { "detail": "\/Users\/\/myproject\/Sources\/MyClass.m:241:97:\/\/ \/ error: instance method 'fetch' not found ; did you mean 'fetchIt'?\r\n myclass:[self.myService fetch]\r ^~~~~~~~~~~~~~\r fetch\r\n 1 error generated.\r", "characterRangeEnd": 13815, "id": "3E6EF185-6AC1-4E95-87E8-E305F41916E9", "endingColumn": 97, "parentIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_8860", "day": "2020-11-02T00:00:00Z", "type": "clangError", "title": "Instance method 'fetch' not found ; did you mean 'fetchIt'?", "endingLine": 241, "severity": 2, "startingLine": 241, "parentType": "step", "buildIdentifier": "MyMac_34580469-5792-40F3-BEFB-7C5925996F23_1", "startingColumn": 97, "characterRangeStart": 0, "documentURL": "file:\/\/\/Users\/\/myproject\/Sources\/MyClass.m" } ] ``` -------------------------------- ### Fetch Daily Counts Source: https://xcmetrics.io/docs/Protocols/StatisticsRepository.html Fetches counts for a date range, sorted by date. Use to get aggregated build and error counts over a period. ```swift func getDayCounts(from: Date, to: Date, using eventLoop: EventLoop) -> EventLoopFuture<[DayCount]> ``` -------------------------------- ### BuildHost.init() Source: https://xcmetrics.io/docs/Classes/BuildHost.html Initializes a new instance of the BuildHost class. ```APIDOC ## BuildHost.init() ### Description Initializes a new instance of the BuildHost class. ### Declaration Swift ```swift public init() ``` ``` -------------------------------- ### init(day:) Source: https://xcmetrics.io/docs/Classes/DayBuildTime.html Initializes a new instance of DayBuildTime with a specified day. ```APIDOC ## init(day:) ### Description Initializes a new instance of DayBuildTime with a specified day. ### Parameters #### Path Parameters - **day** (Date) - Required - The date for which to create the DayBuildTime entry. ### Declaration Swift ```swift public convenience init(day: Date) ``` ``` -------------------------------- ### Run with Configuration Method Source: https://xcmetrics.io/docs/Structs/XCMetrics.html Executes XCMetrics with a provided configuration, including optional custom plugins. ```swift public func run(with configuration: XCMetricsConfiguration) ``` -------------------------------- ### Configure Application Source: https://xcmetrics.io/docs/Other%20Functions.html Use this function to configure the application. It takes an Application instance as input. ```swift public func configure(_ app: Application) throws ``` -------------------------------- ### init() Source: https://xcmetrics.io/docs/Classes/DayBuildTime.html Initializes a new instance of DayBuildTime with default values. ```APIDOC ## init() ### Description Initializes a new instance of DayBuildTime with default values. ### Declaration Swift ```swift public convenience init() ``` ``` -------------------------------- ### Get Build Metadata Source: https://xcmetrics.io/docs/Structs/BuildController.html Retrieves the metadata associated with a build, filtered by build ID. Metadata is returned as a JSON object. ```APIDOC ## GET /v1/build/metadata/ ### Description Endpoint that returns the metadata sent using XCMetrics plugins for the given `Build`. The metadata is returned as a JSON object where each data is a key-value pair of `String`s. ### Method GET ### Endpoint /v1/build/metadata/ ### Parameters #### Path Parameters - **buildId** (string) - Required - `Build`‘s identifier ### Response #### Success Response (200) - **metadata** (object) - Key-value pairs of strings representing metadata. - **id** (string) - **day** (string) - **buildIdentifier** (string) ### Response Example { "metadata": { "anotherKey": "42", "thirdKey": "Third value", "aKey": "value1" }, "id": "C1CDF2CE-0CC2-49C3-B8A2-481E67020CB8", "day": "2020-11-02T00:00:00Z", "buildIdentifier": "MyMac_0B9294B4-7E5A-4D40-91AB-5953A5075785_1" } ``` -------------------------------- ### Create a New SPM Package Source: https://xcmetrics.io/docs/getting-started.html Use this command to initialize a new Swift Package Manager executable project. ```bash swift package init --type executable ``` -------------------------------- ### Run Method Source: https://xcmetrics.io/docs/Structs/XCMetrics.html Executes XCMetrics. Throws an error if required arguments are missing or invalid. ```swift public func run() throws ``` -------------------------------- ### Create Daily Build Time Source: https://xcmetrics.io/docs/Protocols/StatisticsRepository.html Calculates and stores build time information for a given day. Use to record daily build performance. ```swift func createDayBuildTime(day: Date, using eventLoop: EventLoop) -> EventLoopFuture ``` -------------------------------- ### XCMetricsConfiguration Initialization Source: https://xcmetrics.io/docs/Classes/XCMetricsConfiguration.html Initializes a new instance of XCMetricsConfiguration. ```APIDOC ## XCMetricsConfiguration() ### Description Default initializer for XCMetricsConfiguration. ### Method init() ### Parameters None ``` -------------------------------- ### DayCount.init(day:) Source: https://xcmetrics.io/docs/Classes/DayCount.html Initializes a new instance of the DayCount class with a specified Date. ```APIDOC ## DayCount.init(day:) ### Description Initializes a new instance of the DayCount class with a specified Date. ### Parameters #### Path Parameters - **day** (Date) - Description: The Date to initialize the DayCount with. ### Declaration Swift ```swift public convenience init(day: Date) ``` ``` -------------------------------- ### Build Class Source: https://xcmetrics.io/docs/Classes/Build.html Provides reference documentation for the Build class, including its type aliases, static properties, initializers, and instance properties. ```APIDOC ## Build Class ### Description Represents a build entity within the system, conforming to Model, Content, and PartitionedByDay protocols. It includes properties for identification and schema definition. ### Properties - **IDValue**: `String` - Type alias for the build's unique identifier. - **schema**: `String` - Static property representing the schema identifier for builds. - **id**: `String?` - The unique identifier for the build instance. This property is marked with `@Build.ID`. ### Initializers - **init()**: Initializes a new instance of the Build class. ``` -------------------------------- ### Open Package.swift with xed Source: https://xcmetrics.io/docs/index.html Use the `xed` command to open the `Package.swift` file in Xcode for development. ```bash xed Package.swift ``` -------------------------------- ### Get Build Counts Source: https://xcmetrics.io/docs/Structs/StatisticsController.html Retrieves a list of daily build counts, including the sum of errors and builds for a specified number of past days. ```APIDOC ## GET /v1/statistics/build/count ### Description Endpoint that returns a list of `DayCount` which includes the sum of errors and builds during a given day. ### Method GET ### Endpoint /v1/statistics/build/count ### Parameters #### Query Parameters - **days** (integer) - Required - How many days to include in the past, starting from the current date ### Response #### Success Response (200) - **id** (string) - The date of the statistics. - **builds** (integer) - The total number of builds for the day. - **errors** (integer) - The total number of errors for the day. ### Response Example ```json [ { "id": "2021-07-14", "builds": 197, "errors": 4 }, ... ] ``` ``` -------------------------------- ### Implement Custom XCMetrics Client with Plugin Source: https://xcmetrics.io/docs/getting-started.html Create a custom XCMetrics client that integrates a plugin, such as ThermalThrottlingPlugin, to collect specific build data. ```swift import Foundation import XCMetricsClient import XCMetricsPlugins public struct SPTXCMetrics { public static func main() { let metrics = XCMetrics.parseOrExit() let configuration = XCMetricsConfiguration() configuration.add(plugin: ThermalThrottlingPlugin().create()) // ThermalThrottlingPlugin lives in XCMetricsPlugins. metrics.run(with: configuration) } } ``` -------------------------------- ### Step Class Source: https://xcmetrics.io/docs/Classes/Step.html Provides reference documentation for the Step class, including its properties and initializers. ```APIDOC ## Step Class ### Description Represents a step within the system, conforming to Model, Content, and PartitionedByDay protocols. It includes properties for identification and schema definition. ### Properties - **IDValue** (`String`): A type alias for the identifier value, representing a unique ID as a String. - **schema** (`String`): A static property representing the schema definition for the Step. - **id** (`String?`): An optional String property representing the unique identifier of the step, annotated with `@Step.ID`. ### Initializers - **init()**: Initializes a new instance of the Step class. ``` -------------------------------- ### Fetch Daily Build Times Source: https://xcmetrics.io/docs/Protocols/StatisticsRepository.html Fetches build times for a date range, sorted by date. Use to analyze build performance over a period. ```swift func getDayBuildTimes(from: Date, to: Date, using eventLoop: EventLoop) -> EventLoopFuture<[DayBuildTime]> ``` -------------------------------- ### DayCount.init() Source: https://xcmetrics.io/docs/Classes/DayCount.html Initializes a new instance of the DayCount class with default values. ```APIDOC ## DayCount.init() ### Description Initializes a new instance of the DayCount class with default values. ### Declaration Swift ```swift public convenience init() ``` ``` -------------------------------- ### JobLogController boot Method Source: https://xcmetrics.io/docs/Structs/JobLogController.html The boot method is part of the RouteCollection protocol, used for defining routes within the controller. ```swift public func boot(routes: RoutesBuilder) throws ``` -------------------------------- ### Deploy XCMetrics Jobs for Multi-Instance Deployments Source: https://xcmetrics.io/docs/how-to-deploy-backend.html For multi-instance deployments, deploy the XCMetrics jobs and service configurations. These are typically used for background processing or batch tasks. ```bash kubectl create -f xcmetrics-jobs-deployment.yaml kubectl create -f xcmetrics-jobs-service.yaml ``` -------------------------------- ### XCMetricsPlugin Initialization Source: https://xcmetrics.io/docs/Structs/XCMetricsPlugin.html Initializes a new XCMetricsPlugin with a unique name and a closure that defines the plugin's execution logic. The body closure receives environment variables and returns custom metrics. ```APIDOC ## init(name:body:) ### Description Initializes a new XCMetricsPlugin. ### Parameters - **name** (String) - Required - A unique name for this plugin. - **body** (PluginBody) - Required - The closure that contains the implementation of this plugin. This closure takes a dictionary of environment variables and returns a dictionary of key-value pairs to be attached to the build metadata. ``` -------------------------------- ### Get Time Interval from ISO Date Source: https://xcmetrics.io/docs/Extensions/String.html Parses a string containing a date in ISO8601 format (e.g., git format) and returns it as a TimeInterval. Returns nil if the date cannot be parsed. ```swift public func getTimeIntervalFromISODate() -> TimeInterval? ``` -------------------------------- ### Force Post-Action Scheme Execution on Build Failure Source: https://xcmetrics.io/docs/getting-started.html Add this attribute to your `BuildAction` tag in the `.xcscheme` file to ensure the post-action scheme runs even if the build fails. ```xml ``` -------------------------------- ### Configure Docker Compose Port Mapping Source: https://xcmetrics.io/docs/run-the-backend-locally.html Example of how to change the Redis port in the docker-compose.yml file. The left port is the host port, and the right port is the container port. This is useful if the default ports (6379 for Redis, 5432 for Postgres) are already in use. ```yaml ports: - "6500:6379" ``` -------------------------------- ### Initializer with Day Source: https://xcmetrics.io/docs/Classes/DayCount.html Declares the public convenience init(day:) initializer that accepts a Date. ```swift public convenience init(day: Date) ``` -------------------------------- ### Configure XCMetrics Launcher for Cloud Run Deployment Source: https://xcmetrics.io/docs/how-to-deploy-backend.html This command configures the XCMetrics launcher to point to the metrics-sync endpoint when deploying on Cloud Run. Ensure your service URL is correctly set. ```bash ${SRCROOT}/../../XCMetricsLauncher ${SRCROOT}/../../.build/release/XCMetrics --name BasicApp --buildDir ${BUILD_DIR} --serviceURL https://yourservice.com/v1/metrics-sync ```