# Orchestrator Logs

> These are diagnostic logs generated by UiPath® Orchestrator regarding its behavior.

## Orchestrator Diagnostic Logs

These are diagnostic logs generated by UiPath® Orchestrator regarding its behavior.

### Enabling UiPath Orchestrator Diagnostic Logs

The UiPath Orchestrator Diagnostic Logs are enabled once UiPath Orchestrator is successfully installed. They rely on the NLog infrastructure and their configuration can be found in the `UiPath.Orchestrator.dll.config` file, under the `<nlog>` tag.

:::note
Please keep in mind that both server exceptions from Orchestrator, and the stack trace on the **Job Details** window, are logged in English, regardless of what language was chosen by the user.
:::

### Targets of the UiPath Orchestrator Diagnostic Logs

All application logs are logged to the Event Viewer at the minimum logging level of **Information**. This is specified by the following lines in the `UiPath.Orchestrator.dll.config` file:

`<target xsi:type="EventLog" name="eventLog" layout="${message}" source="Orchestrator" log="Application" />`

`<logger name="*" minlevel="Info" writeTo="eventLog" />`

Logs generated by the **Jobs Scheduler** have a separate target and logger:

`<target xsi:type="EventLog" name="eventLogQuartz" layout="[Quartz] ${message} ${onexception: ${exception:format=tostring}}" source="Orchestrator" log="Application" />`

`<logger name="Orchestrator.Quartz.*" minlevel="Info" writeTo="eventLogQuartz" />`

Example:

* `Could not create Quartz Job`

Logs generated by **business and other validation rules** have a separate target and logger:

`<target xsi:type="EventLog" name="businessExceptionEventLog" layout="${message}${onexception:${exception:format=tostring:maxInnerExceptionLevel=5:innerFormat=tostring}}" source="Orchestrator.BusinessException" log="Application" />`

`<logger name="BusinessException.*" minlevel="Info" writeTo="businessExceptionEventLog" final="true" />`

These types of error messages are logged in the Event Viewer in the following cases:

* validation issues such as:
  + `Invalid username/email address or password.`
  + `The machine name DOC is already taken`
* business conflicts such as:
  + `License expired!`
  + `The floating robot's session is already active on machine ROQADOCS06!`
  + `The robots already have pending jobs for this Process.`
* not found exceptions such as:
  + `QueueName1 does not exist.`

## Orchestrator Execution Logs

The Orchestrator Execution Logs are sent by the **Robots** connected to it and are displayed in the **Logs** section of the **Jobs** or **Robots** pages. The application receives the data from the Robots, adds its own parameters (**TenantID**, **FolderID**), and forwards the messages to different targets, as specified in the `<nlog>` section from the `UiPath.Orchestrator.dll.config` file.

### Targets of the Orchestrator Execution Logs

By default, all Robot logs are sent to the **Logs** table of the Default Orchestrator Database, where UiPath Orchestrator stores other information as well.

You can, however, choose to send Robot logs to a different database by configuring it in the `target xsi:type="Database" connectionString="..."` section of the `UiPath.Orchestrator.dll.config` file.

The **Logs** page displays information from the **Logs** table of the **Default Database**. So, if this section does not exist, or the logs are saved to a different database, the page is empty. All parameters should be according to the table schema, which looks like this:

```
<target xsi:type="Database" name="database" connectionString="${ui-connection-strings:item=Default}" keepConnection="true">
 <commandText>
  insert into dbo.Logs (OrganizationUnitId, TenantId, TimeStamp, Level, WindowsIdentity, ProcessName, JobKey, Message, RawMessage)
  values (@organizationUnitId, @tenantId, @timeStamp, @level, @windowsIdentity, @processName, @jobId, @message, @rawMessage)
 </commandText>
  <parameter name="@organizationUnitId" layout="${event-properties:item=organizationUnitId}" />
  <parameter name="@tenantId" layout="${event-properties:item=tenantId}" />
  <parameter name="@timeStamp" layout="${date}" />
  <parameter name="@level" layout="${event-properties:item=levelOrdinal}" />
  <parameter name="@windowsIdentity" layout="${event-properties:item=windowsIdentity}" />
  <parameter name="@processName" layout="${event-properties:item=processName}" />
  <parameter name="@jobId" layout="${event-properties:item=jobId}" />
  <parameter name="@message" layout="${message}" />
  <parameter name="@rawMessage" layout="${event-properties:item=rawMessage}" />
</target>
 <logger name="Robot.*" writeTo="database" final="true" />
```

Other targets can be added to the logs by configuring the `UiPath.Orchestrator.dll.config` file. A list of available targets can be found [here](https://github.com/nlog/nlog/wiki/Targets).

:::note
When upgrading Orchestrator, Nlog targets are deleted and recreated, as follows:
* Upon upgrade to 2022.4, Nlog database targets are reverted to their default values.
* Upon upgrade to 2022.10, Nlog database targets are deleted and replaced with new and improved targets.
This covers `database`, `monitoring`, and `insightsRobotLogs` targets.
:::
:::important
If the number of Robot logs stored in the table is higher than 1 million, we recommend creating the following index for improved search performance:
:::

```
CREATE NONCLUSTERED INDEX [IX_Search] ON [dbo].[Logs]
(
[TenantId] ASC,
[OrganizationUnitId] ASC,
[Level] ASC,
[TimeStamp] DESC
)WITH (STATISTICS_NORECOMPUTE = OFF, DROP_EXISTING = OFF, ONLINE = OFF, OPTIMIZE_FOR_SEQUENTIAL_KEY = OFF) ON [PRIMARY]
GO
```

### Elasticsearch Server

By default, there’s an Elasticsearch target configured from the installation script. The index is different for each tenant, but this can be configured from the specified target in the `<nlog>` section.

#### For Elasticsearch versions lower than 8.0:

```
<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
<target xsi:type="ElasticSearch" name="robotElastic" uri="uritoelasticsearchnode" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,organizationId,indexName" />
</target>
</target>
```

#### For Elasticsearch versions 8.0 and higher:

```
<target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
<target xsi:type="ElasticSearch" name="robotElastic" uri="uritoelasticsearchnode" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="" enableApiVersioningHeader="true" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,organizationId,indexName" />
</target>
</target>
```

In order for Elasticsearch versions 8.0 and higher to work properly, these parameters are set as follows:

* `documentType` is empty.
* `enableApiVersioningHeader` is set to `true`.
:::note
The option to save robot logs to an Elasticsearch server only becomes effective once you configure it, and is not applied retroactively. This means that you will no longer have access to any logs that were already in the database at the time you configured the option, because logs can only be retrieved and displayed from a single destination.
:::

### X-PACK Authentication

:::note
By default, the Elasticsearch security features are disabled if you have a basic or trial license. We strongly recommend that you enable them.
:::

#### Username-and-password Authentication

To enable authentication via a username and password, you need to take the following steps:

1. Configure the Elasticsearch server as follows:
   * Add the `xpack.security.enabled` setting to the `elasticsearch.yml` configuration file.
   * Set up a username and password.

     For more details on this, see the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html).

2. Configure Orchestrator's `UiPath.Orchestrator.dll.config` file as follows:
* **Option 1**: If you do not use an NLog target, you need to configure the following parameters: `Logs.Elasticsearch.Username` and `Logs.Elasticsearch.Password`. Make sure their values match the Elasticsearch settings from Step 1.
* **Option 2**: If `Logs.RobotLogs.ReadTarget` is set to an NLog target (for example, `robotElasticBuffer`), and the `Logs.Elasticsearch.Nodes` setting is not specified, configure the target by adding the following: `requireAuth="true" username="XPACKuser" password="p@$$w0rd"`. Make sure these parameter values match the Elasticsearch settings from Step 1.

  For more on these parameters, see the [UiPath.Orchestrator.dll.config](https://docs.uipath.com/orchestrator/standalone/2022.10/installation-guide/uipath-orchestrator-dll-config) page. For a configuration example, see the following:

  ```
  <target name="robotElasticBuffer" xsi:type="BufferingWrapper" flushTimeout="5000">
          <target xsi:type="ElasticSearch" name="robotElastic" uri="" requireAuth="true" username="XPACKusername" password="p@$$w0rd" index="${event-properties:item=indexName}-${date:format=yyyy.MM}" documentType="logEvent" includeAllProperties="true" layout="${message}" excludedProperties="agentSessionId,tenantId,indexName" />
        </target>
  ```
* **Option 3**: If `Logs.RobotLogs.ReadTarget` is set to an NLog target ( for example, `robotElasticBuffer`), and an Elasticsearch node is specified via the `Logs.Elasticsearch.Nodes` setting, you need to explicitly configure it (as it overrides the NLog target settings), and make sure to also add the following: `requireAuth="true" username="XPACKuser" password="p@$$w0rd"`. Make sure these parameter values match the Elasticsearch settings from Step 1.

#### OAuth2 Authentication

To switch to OAuth2 as an authentication method for Elasticsearch, you need to take the following steps. Note that you need to provide your current credentials to switch to this token-based authentication method.

1. Configure the Elasticsearch server as follows:
    1. Enable TLS (HTTPS) for the transport layer.
    2. Update the following settings in the `elasticsearch.yml` configuration file:

   * `xpack.security.authc.token.enabled: true`
   * `xpack.security.enabled: true`
   * `xpack.security.authc.token.timeout` - This settings is optional and controls for how long a token is valid. By default, its value is set to 20 minutes.

     For more details on this, see the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-settings.html).

2. Update the following parameters in Orchestrator's `UiPath.Orchestrator.dll.config` file to reflect the settings you opted for at Step 1.
   * `Logs.Elasticsearch.TlsEnabled = ”true”` - By default, this parameter is set to `true` and ensures TLC (HTTPS) is enabled.
   * `Logs.Elasticsearch.OAuthEnabled = ”true”` - By default, this parameter is set to `false`. For more on this, see [`Logs.Elasticsearch.OAuthEnabled`](https://docs.uipath.com/orchestrator/standalone/2022.10/installation-guide/uipath-orchestrator-dll-config).
   * `Logs.Elasticsearch.OAuthExpireInSeconds = ”1200”` - This parameter is optional unless the default value of `1200` is changed in the Elasticsearch `xpack.security.authc.token.timeout` setting. This parameter must have the same value as in the Elasticsearch configuration. For more on this, see [`Logs.Elasticsearch.OAuthExpireInSeconds`](https://docs.uipath.com/orchestrator/standalone/2022.10/installation-guide/uipath-orchestrator-dll-config).
     :::note
     The first two steps help you configure a token-based authentication mechanism for reading logs. If you use NLog, an additional step is needed.
     :::
3. To enable OAuth2 for Nlog, make sure to also configure the following parameter in Orchestrator's `UiPath.Orchestrator.dll.config` file. Note that you must fill in the [username and password](https://docs.uipath.com/orchestrator/standalone/2025.10/user-guide/orchestrator-logs#orchestrator-logs) for authentication in Elasticsearch because the initial token is generated based on those credentials.
   * `OAuthEnabled = “true”` - By default, it is set to `false`. For more on this, see the [UiPath.Orchestrator.dll.config](https://docs.uipath.com/orchestrator/standalone/2022.10/installation-guide/uipath-orchestrator-dll-config) page.
     :::important
     If `Logs.RobotLogs.ReadTarget` is set to an NLog target (for example, `robotElasticBuffer`), and the `Logs.Elasticsearch.Nodes` setting is not specified, then the `Logs.Elasticsearch.OAuthEnabled` is filled from the NLog target configuration. Same logic is applied for username and password.
     :::

#### API key authentication

To enable authentication via API key, follow the stepts outlined below.

1. Generate the API key by following [these steps](https://www.elastic.co/guide/en/elasticsearch/reference/8.6/security-api-create-api-key.html).
2. [Store](https://learn.microsoft.com/en-us/azure/key-vault/secrets/quick-create-portal#add-a-secret-to-key-vault) the API key as a secret in your Azure key vault.
3. Configure the following Nlog target parameters with your data, thus creating a connection between Orchestrator and your key vault which allows the key to be retrieved:
   ```
   apiKeyEnabled="true"
   apiKeyProvider="AzureKeyVault"
   apiKeySecretName="<SecretName>"
   azureKeyVaultUri="<KeyVaultUri>"
   azureKeyVaultDirectoryId="<KeyVaultDirectoryId>"
   azureKeyVaultClientId="<KeyVaultClientId>"
   azureKeyVaultCertificateThumbprint="<KeyVaultCertificateThumbprint>"
   azureKeyVaultCertificateStoreLocation="CurrentUser/LocalMachine"
   ```

   The following parameters need to be edited with your values:

   * `<SecretName>` - the name you set for your API key in the key vault
   * `<KeyVaultUri>` - the URI of your key vault
   * `<KeyVaultDirectoryId>` - your key vault directory ID
   * `<KeyVaultClientId>` - your key vault client ID
   * `<KeyVaultCertificateThumbprint>` - the thumbprint of your key vault certificate
   * `CurrentUser/LocalMachine` - the location where the certificate is stored

##### API key expiration

By default, API keys do not expire, but you can still choose to set an expiration date for them.

If your API key is set to expire, you must generate a new and store it in the key vault before the expiration date, so as to make sure that Orchestrator can always retrieve a valid key.

Orchestrator reads API keys from the key vault every 15 minutes, so this is the maximum amount of delay you can expect before your new key is propagated.