Collect OCF Logs on Customer-Managed Instances

Customer Managed Applies to customer-managed instances of Alation

In a customer-managed (on-premise) setup, you have direct access to the underlying server where Alation is installed.

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.