# Appendix: Audit Event Correlation

### Correlation by **`identifier`** Field

To correlate events within a single service for a request, you can use the **`identifier`** field; such as, to correlate the **`request-authorized`** and the various access request/grant/denial lifecycle events.

Although you can also correlate the these events using the OpenTelemetry **`traceId`** field, the **`identifier`** field may be preferred as as the **`identifier`** field is managed by ESS whereas the **`traceId`** is subject to how the client specifies the **`traceId`** for its requests.

### OpenTelemetry **`traceId`** Field

Audit messages include the client-specified [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) **`traceId`** (along with other OpenTelemetry data) in the **`instrument`** field. This field may be used to correlate messages across services.

For example, if a start app specifies a **`traceId`** for its start flow (i.e., user registration to get a WebID and a Pod), you can use this client-specified **`traceId`** value to correlate the events associated with that start flow:

{% hint style="info" %}
**Note**

* In the example messages below, various fields have been omitted for clarity/brevity.
* Correlation by **`traceId`** may not be suitable for audit trail purposes as the **`traceId`** is managed by the client.
  {% endhint %}

<pre class="language-json"><code class="lang-json">{
   //...
   "name" : "webid-created",
   "summary" : "WebId was created",
   //...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://id.example.com/owliverowner",
         "name" : "owliverowner"
      }
   ],
   "object" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "PersonalProfileDocument"
         ]
      }
   ],

   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "f59408a78e40f5a8",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "fafb4c391e0d5189",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "5244408d0f56431ba727cbdd4c177d61",
   "published" : "2023-12-06T01:57:27.835491323Z"
}

{
   //...
   "name" : "provisioned-pod-access-control",
   "summary" : "Provisioned Pod access control",
   //...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://provision.example.com/"
      }
   ],
   "object" : [ ],
   "instrument" : [
      {
         "type" : [
            "Storage"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/"
      },
      {
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ],
         "spanId" : "97e22fca05e84103",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "163e168f726abcce"
      }
   ],
   "result" : [ ],
   "identifier" : "6c1ce07ec6b54ee09c21486d4366b277",
   "published" : "2023-12-06T01:57:30.672004Z"
}


{
   // ...
   "name" : "resource-created",
   "summary" : "Resource has been created",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "accessControl" : [
            "https://authorization.example.com/1fb6b127afb9458b9cf7d405d1c47dde"
         ],
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/"
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "5a0fbc0f4aeb0c8f",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "15e8a1b3cd149acf",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:30.736939618Z"
}

{
   // ...
   "name" : "acr-created",
   "summary" : "ACR has been created",
   // ...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://provision.example.com/"
      }
   ],
   "object" : [
      {
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/"
      },
      {
         "type" : [
            "AccessControlResource"
         ],
         "id" : "https://authorization.example.com/1fb6b127afb9458b9cf7d405d1c47dde"
      }
   ],
   "instrument" : [
      {
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ],
         "spanId" : "5637a071550bc999",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "91d7a028b1bdb074"
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "83ceb448725e4e3c8bef7576e941e957",
   "published" : "2023-12-06T01:57:31.444925619Z"
}

{
   // ...
   "name" : "resource-created",
   "summary" : "Resource has been created",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "generated" : "50ece2b2-f46b-4dca-90cb-3a42ee07f6fc",
         "accessControl" : [
            "https://authorization.example.com/0e7c68f9354742a9bbc29da64dcd14c8"
         ],
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/profile"
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "3cdec0dcecd7538d",
         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
         "parentId" : "996f99df65b6ebc2",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:31.555962708Z"
}

{
   // ...
   "name" : "acr-created",
   "summary" : "ACR has been created",
   // ...
   "actor" : [
      {
         "type" : [
            "Agent"
         ],
         "id" : "https://provision.example.com/"
      }
   ],
   "object" : [
      {
         "type" : [
            "Resource"
         ],
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/profile"
      },
      {
         "type" : [
            "AccessControlResource"
         ],
         "id" : "https://authorization.example.com/0e7c68f9354742a9bbc29da64dcd14c8"
      }
   ],
   "instrument" : [
      {
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ],
         "spanId" : "5b515094a69aaa03",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "ce6251cc1b12dbda"
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "dccd5eb3957d40dcb9974081d17b82fe",
   "published" : "2023-12-06T01:57:31.663061454Z"
}
{
   // ...
   "name" : "resource-updated",
   "summary" : "Resource timestamp has been updated",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "Resource"
         ]
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "3b5ec01c1bbf7cc2",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "996f99df65b6ebc2",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:31.743024556Z"
}

{
   // ...
   "name" : "pod-provisioned",
   "summary" : "Pod provisioned",
   // ...
   "actor" : [
      {
         "id" : "https://id.example.com/owliverowner",
         "type" : [
            "Agent"
         ]
      }
   ],
   "object" : [
      {
         "id" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "Storage"
         ]
      }
   ],
   "instrument" : [
      {
         "id" : "https://start.example.com/app/id",
         "summary" : "Client identifier"
      },
      {
         "spanId" : "36cbd6bd8488a2d9",
<strong>         "traceId" : "1551e335cfde87a7df87d3242f2d060e",
</strong>         "parentId" : "765195098215788f",
         "name" : "OpenTelemetry Span Context",
         "isSampled" : true,
         "type" : [
            "SpanContext"
         ]
      },
      {
         "hasDataSubject" : {
            "id" : "https://id.example.com/owliverowner",
            "type" : [
               "https://w3id.org/dpv#DataSubject"
            ]
         },
         "hasStorage" : "https://storage.example.com/7865026e-5450-44a2-82e5-67c8b28e905d/",
         "type" : [
            "http://www.w3.org/2004/02/skos/core#Concept"
         ]
      }
   ],
   "result" : [ ],
   "identifier" : "cf6507cf8b084f5ebfa489c300ae1ad4",
   "published" : "2023-12-06T01:57:31.782133926Z"
}
</code></pre>

For more information on OpenTelemetry, refer to the [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) documentation.

#### Correlation by Application-Defined Property

ESS can propagate [application-defined metadata/properties](https://docs.inrupt.com/ess/latest/administration/application-defined-metadata/) sent in client requests to include in associated log messages, associated audit events, and associated response to the request.

Depending upon the [configuration](https://docs.inrupt.com/ess/latest/administration/application-defined-metadata#configuration), ESS audit events can include the application-defined request metadata in the **`instrument`** field:

{% hint style="info" %}
**Note**

* In the example messages below, various fields have been omitted for clarity/brevity.
* Correlation by client defined properties may not be suitable for audit trail purposes as these properties are subject to how the client manages these properties as well as the ESS configuration.
  {% endhint %}

```json
{
   // ...
   "name" : "request-authorized",
   "summary" : "Request has been authorized",
   // ...
   "instrument" : [
      // ...
      {

        "name" : "Application-Defined Request Metadata",
        "items": [
           {
              "mediaType" : "text/plain",
              "name" : "x-correlation-id",
              "content" : "2049875809728750827498245084"
           },
           {
              "mediaType":"text/plain",
              "name":"my-client-version",
              "content":"1.0.3"
           }
        ],
        "type":[
           "urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"
        ]
      }
      // ...
   ],
   // ...
}
{
   // ...
   "name" : "access-request-created",
   "summary" : ""Access Request has been created",

   "instrument" : [
      // ...
      {

        "name" : "Application-Defined Request Metadata",
        "items": [
           {
              "mediaType" : "text/plain",
              "name" : "x-correlation-id",
              "content" : "2049875809728750827498245084"
           },
           {
              "mediaType":"text/plain",
              "name":"my-client-version",
              "content":"1.0.3"
           }
        ],
        "type":[
           "urn:uuid:1a05e301-4013-40c9-bae7-5d719b7151c8"
        ]
      }
      // ...

   ],
   // ...
 }
```