Collect OCF Logs on Customer-Managed Instances

Customer Managed Applies to customer-managed instances of Alation

Applies to 2026.7 and newer

In a customer-managed (on-premises) setup, you can retrieve connector logs from the Alation UI or directly from the server.

Download Logs from the Alation UI

The connector detail page in the Alation UI lets you download logs without direct server access.

To download connector logs from the UI:

  1. In Admin Settings, go to Manage Connectors.

  2. Click the name of the connector to open its detail page.

  3. In the Logs area, switch between the Connector Logs and System Logs tabs to preview log content.

  4. Click Download to save an unencrypted .tar.gz archive that contains both connector and system logs.

Note

This method also applies in the following case:

  • Connectors are deployed on an agent that runs on customer infrastructure as part of an Alation Cloud Service deployment.

  • Logs for these connectors are not available in Grafana.

  • Retrieve these logs by using this download method or the command-line methods below.

To enable encryption for connector log downloads, set the alation.feature_flags.DEV_enable_encrypted_log_on_prem_download flag to True in alation_conf. This is the same flag used to control encryption for server log downloads. See Logging Tab: Customer Managed for instructions.

For cases where the UI is not available or you need additional log files, use the command-line methods described below.

Access the Server

You need SSH access to the Alation server. The user performing these steps usually requires appropriate permissions (for example, root access or membership in a specific Alation service group) to navigate directories and read log files.

To access the server:

  1. Use SSH to connect to the Alation server.

  2. Enter the Alation shell using the following command:

    sudo /etc/init.d/alation shell

Locate the Log Files

OCF connector logs and logs from related Alation services (like Celery, executing connector tasks) are stored in specific directories within the Alation installation path inside the Alation shell: /opt/alation/site/logs/.

Locate the following log files in the above-mentioned path:

  • connector.log

  • connector_err.log

  • connector_out.log

  • connector_check.log

  • connector_check_error.log

  • celery-default_error.log

  • ocf.log

You can also use the following commands to retrieve specific information from the Docker logs:

Alation Connector Manager Logs

The Alation Connector Manager (agent) coordinates connector operations.

View Live Logs

To monitor the agent logs in real-time tail, use the following command on the Alation server outside of the Alation shell:

sudo docker logs -f agent

  • -f: Follows the log output

  • Press Ctrl+C to stop tailing

Write Logs to a File

To save the complete current agent logs to a file named agent.logs:

sudo docker logs agent > agent.logs 2>&1

  • >: Redirects standard output stdout to the file.

  • 2>&1: Redirects standard error stderr to the same location as stdout, ensuring both logs and errors are captured in the file.

Individual Connector Logs

Each connector instance generates its own logs.

Obtain the Connector ID

You need the specific ID of a connector to retrieve its logs.

  1. List all connectors with their IDs and names using the following command in the Alation shell:

    sudo su alation

alation_ypireti list --fields ID,name

  2. Identify the id of the target connector from the output.

View Recent Live Logs

To view the last 100 lines of a specific connector’s log and follow new entries:

  • Using Docker logs: Replace <connector_id> with the actual ID.

    sudo docker logs -f --tail 100 <connector_id>

    • -f: Follows the log output.

    • --tail 100: Shows the last 100 lines.

  • Using kratos: Replace <connector_id> with the actual ID.

    alation_ypireti kratos logs --tail <number of rows> <CONNECTOR_ID>

    This command provides a similar tailing function via the Alation utility Kratos.

Write Logs to a File

To save the complete current logs for a specific connector to a file:

  • Using Docker logs: Replace <connector_id> with the ID and <connector_name> with a descriptive name for the log file.

    sudo docker logs <connector_id> > <connector_name>.logs 2>&1

  • Using kratos: Replace <connector_id> with the ID. The output in this example will be saved to connector.log.

    alation_ypireti kratos logs <connector_id> > connector.log 2>&1

Write Logs Since a Specific Date/Time to a File

To retrieve logs for a specific connector starting from a particular date and time and save them to a file:

  • Using kratos: Replace <connector_id> with the ID and adjust the date/time string (YYYY-MM-DD HH:MM:SS) as needed.

    Example: Logs since August 15, 2020, 00:00:00

    alation_ypireti kratos logs --since "2025-04-06 00:00:00" <connector_id>

    • --since: Specifies the start time for log retrieval. Use the format “YYYY-MM-DD HH:MM:SS” or similar recognized by Docker logs. Ensure the timestamp format is correct for your environment.

Once you’ve identified the relevant log files, compress them into a single archive (for example, a .zip or .tar.gz file). It is recommended to include logs covering the time frame just before, during, and shortly after the error occurred.

When submitting these logs, also provide Alation Support with context, such as:

  • The name and version of the OCF connector.

  • The ID of the job that failed (if applicable). The job ID will be available in the MDE job history; see View the MDE Job History for details.

  • The exact timestamp (including timezone) when the error was observed.

  • Any error messages if displayed in the Alation user interface.

  • The steps that resulted in the error.