Connection Failure log request examples

Use Citrix Monitor Service API to get the details of connection failures.

NOTE: The request examples of this section target cloud setups. However the OData queries also apply to on-premises setups. Simply adjust the request URL to be of the form http[s]://{MonitorServiceHost}/Citrix/Monitor/OData/v4/Data/{ODataQuery} and change the authentication to NTLM.

Prerequisites

  • Read the Get started with Citrix Cloud APIs section to ensure that you have a valid bearer token.
  • Use the endpoint https://{ApiGatewayEndpoint}/monitorodata/ConnectionFailureLogs for your requests. See Supported API Gateway endpoints for a list of region specific API gateway endpoints.
  • Invoke the API described in this document from a client host.

ConnectionFailureLogs for target time

  • $filter=(FailureDate ge 2024-07-30T00:00:00Z and FailureDate le 2024-07-31T00:00:00Z) represents the target time range.

Request

GET /monitorodata/ConnectionFailureLogs?$filter=(FailureDate ge 2024-07-30T00:00:00Z and FailureDate le 2024-07-31T00:00:00Z) HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#ConnectionFailureLogs",
    "value": [
        {
            "Id": 128230,
            "SessionKey": "77337e10-1ad2-4e95-8990-b83a420405ed",
            "FailureDate": "2024-07-30T01:02:49.37Z",
            "UserId": 1225,
            "MachineId": "53e6e3b6-a874-4e9b-ab4b-61241c34f241",
            "ConnectionFailureEnumValue": 4,
            "CreatedDate": "2024-07-30T01:02:49.37Z",
            "ModifiedDate": "2024-07-30T01:02:51.387Z"
        },
        {
            "Id": 128231,
            "SessionKey": "77337e10-1ad2-4e95-8990-b83a420405ed",
            "FailureDate": "2024-07-30T01:19:49.98Z",
            "UserId": 1225,
            "MachineId": "53e6e3b6-a874-4e9b-ab4b-61241c34f241",
            "ConnectionFailureEnumValue": 4,
            "CreatedDate": "2024-07-30T01:19:49.98Z",
            "ModifiedDate": "2024-07-30T01:19:52.727Z"
        },
    ]
}
<!--NeedCopy-->
  • With $expand operation to get the related Machine, Session and User details for ConnectionFailureLogs.

Request

GET /monitorodata/ConnectionFailureLogs?$filter=(FailureDate ge 2024-07-31T00:00:00Z)&$expand=Machine($select=Name,CurrentRegistrationState,IsInMaintenanceMode),User($select=Sid,Upn,UserName,Domain),Session HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#ConnectionFailureLogs",
    "value": [
        {
            "Id": 128249,
            "SessionKey": "0b3e91c9-b324-4a32-871a-70cc8e9a7a2a",
            "FailureDate": "2024-07-31T00:23:48.84Z",
            "UserId": 1308,
            "MachineId": "3563b00d-4c5b-4658-8fa2-9eddbf017e0b",
            "ConnectionFailureEnumValue": 3,
            "CreatedDate": "2024-07-31T00:23:48.84Z",
            "ModifiedDate": "2024-07-31T00:23:51.547Z",
            "Machine": {
                "Name": "ENG\\ra-w10-cvad010",
                "IsInMaintenanceMode": false,
                "CurrentRegistrationState": 2
            },
            "User": {
                "Sid": "S-1-5-21-1076320343-3137401123-2908695819-435603",
                "Upn": "igor.polozkov@citrix.com",
                "UserName": "igorp",
                "Domain": "CITRITE"
            },
            "Session": {
                "SessionKey": "0b3e91c9-b324-4a32-871a-70cc8e9a7a2a",
                "StartDate": "2024-07-19T13:30:02.003Z",
                "LogOnDuration": 149790,
                "EndDate": null,
                "ExitCode": 1,
                "FailureId": 11,
                "FailureDate": "2024-07-31T13:38:20.69Z",
                "ConnectionState": 2,
                "SessionIdleTime": null,
                "ConnectionStateChangeDate": "2024-07-25T13:57:20.283Z",
                "LifecycleState": 0,
                "CurrentConnectionId": 885929,
                "UserId": 1308,
                "MachineId": "3563b00d-4c5b-4658-8fa2-9eddbf017e0b",
                "SessionType": 0,
                "IsAnonymous": false,
                "PublishedDesktopId": 20,
                "CreatedDate": "2024-07-19T13:32:30.267Z",
                "ModifiedDate": "2024-07-25T13:57:20.283Z"
            }
        }
    ]
}
<!--NeedCopy-->

Count by ConnectionFailureEnumValue

  • With groupby and aggregate operations, you can get the ConnectionFailureLogs count grouped by ConnectionFailureEnumValue.

Request

GET /monitorodata/ConnectionFailureLogs?$apply=filter(CreatedDate gt 2024-07-01T00:00:00.00Z )/groupby((ConnectionFailureEnumValue), aggregate(id with countdistinct as FailureCount)) HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#ConnectionFailureLogs",
    "value": [
        {
            "@odata.id": null,
            "ConnectionFailureEnumValue": 3,
            "FailureCount": 63
        },
        {
            "@odata.id": null,
            "ConnectionFailureEnumValue": 4,
            "FailureCount": 178
        }
    ]
}
<!--NeedCopy-->

Users with a high number of session failures

As part of this example, we query the ConnectionFailureLogs entity, where session failures are logged. The linking to the Users entity is done through the Sessions entity. We group by the user entity, get the distinct count of failures and select the top items.

Request

GET /monitorodata/ConnectionFailureLogs?$apply=filter(Session/StartDate ge 2025-05-01)/groupby((Session/User/FullName,ConnectionFailureEnumValue), aggregate(Id with countdistinct as FailureCount))&$orderby=FailureCount desc&$top=20 HTTP/1.1
Host: api.cloud.com
Authorization: CWSAuth bearer=<Token>
Citrix-CustomerId: <CustomerId>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Date: Thu, 01 Aug 2024 06:23:00 GMT
Content-Type: application/json; odata.metadata=minimal
Content-Length: 5506
Connection: keep-alive
odata-version: 4.0

{
    "@odata.context": "https://api.cloud.com/monitorodata/$metadata#ConnectionFailureLogs",
    "value": [
        {
            "@odata.id":null,
            "ConnectionFailureEnumValue":100,
            "FailureCount":8,
            "Session":{
                "@odata.id":null,
                "User":{
                    "@odata.id":null,
                    "FullName":"User Name"
                }
            }
        }
    ]
}
<!--NeedCopy-->
Resources
Citrix Monitor Service API OpenAPI Specification
Copy Download
Connection Failure log request examples