XCMetrics

https://xcmetrics.io/docs
Admin
XCMetrics is a tool designed to collect Xcode build metrics, helping developers monitor build times,...
Tokens:26,633
Snippets:318
Trust Score:6
Update:4 months ago
Show doc for...
Tokens:
Raw
### 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<Page<Build>>
```

```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<DayBuildTime>
```

--------------------------------

### 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/<buildId>

### Description
Retrieves a list of compilation warnings that occurred during a specific build.

### Method
GET

### Endpoint
/v1/build/warning/<buildId>

### 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\/<redacted>\/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/<buildId>

### 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/<buildId>

### 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\/<redacted>\/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/<buildId>

### Description
Retrieves a list of compilation errors that occurred during a specific build.

### Method
GET

### Endpoint
/v1/build/error/<buildId>

### 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\/<redacted>\/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\/<redacted>\/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\/<redacted>\/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/<buildId>

### Description
Endpoint that returns the data of the host used in the given `Build`.

### Method
GET

### Endpoint
/v1/build/host/<buildId>

### 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<DayCount>
```

--------------------------------

### 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<BuildMetadata>
```

--------------------------------

### 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\/<redacted>\/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\/<redacted>\/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/<buildId>

### 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/<buildId>

### 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<Void>
```

--------------------------------

### 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
<BuildAction runPostActionsOnFailure="YES"/>
```

--------------------------------

### 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

```
Tokens:
Raw