Container Diagnostic Collection

Version

Function Introduction

When FineReport, FineBI, FineDataLink, or FineBI engine-related components fail to start, restart repeatedly, or fail health checks, you (the admin) usually need to collect application logs, container logs, Docker events, and thread dumps separately. This requires logging in to nodes, switching between entry points, and aligning timelines manually, which slows troubleshooting and may miss key evidence. Diagnostic Collection collects, aligns, and packages these materials in one operation.

This function is recommended in the following scenarios:

1. A container fails to start or exits immediately after startup, and you need to locate startup errors.

2. A container restarts repeatedly, and you need to align Docker events with the application log timeline.

3. Health checks keep failing (in the unhealthy status), and you need thread dumps to determine whether the application is stuck.

4. You need to submit complete on-site diagnostic materials to technical support or the FanRuan R&D team.

Note:

This function only exports diagnostic materials and does not generate diagnostic conclusions automatically. For routine performance inspections, use Health Inspection or Deep Inspection.

Before starting diagnostic collection, make sure that the following requirements have been met.

This section describes how to start diagnostic collection from Component Management and obtain a diagnostic package that can be submitted to R&D.

Accessing the Collection Entry

Perform the following operations to locate the Diagnostic Collection button:

1. Log in to FineOps and select the target O&M project. Choose Maintenance > Component Management.

2. Locate the target container in the container list of the component.

3. Click the expand arrow on the far right of the Operation column for the container, and select Diagnostic Collection from the drop-down menu.

Note:

The drop-down menu is displayed only for component containers that support diagnostic collection. The entry is still available when the container status is not running.

Setting the Time Window and Starting Collection

1. In the Diagnostic Collection pop-up window, use the Start Time control to select a time point before the failure occurred, for example, 2026-10-19 13:53:05.

• After you select the start time, the system collects data within one hour after the start time. If the duration is less than one hour, data is collected until the current time.

• Set the start time 5 to 10 minutes before the failure time to include pre-startup logs.

• A single task covers at most 60 minutes. For longer issues, run collection multiple times.

2. Check the Latest Container Startup Time shown in the pop-up window to determine whether the selected time window covers the current startup process.

3. Click Start Collection.

Downloading and Verifying the Diagnostic Package

1. Wait until the collection task is complete. The browser automatically downloads a single ZIP file. The file name format is IP address_Container name_Export time.zip, for example, 192.168.101.91_fanruan240727164101_bi7-web_20260826112424.zip.

2. Decompress the package, open manifest.json, and check whether the status of each material in artifacts is SUCCESS.

3. If any item is not SUCCESS, troubleshoot based on the reason field and the "Troubleshooting" section. Adjust the time window and collect diagnostics again if needed.

After the collection task is complete, the browser automatically downloads a single ZIP file.

Package Content

Files are stored at the root level and are not nested in directories or further compressed. The following table describes each file, its source, and its purpose.

Troubleshooting

After decompressing the diagnostic package, open manifest.json and check whether the status of each material in artifacts is SUCCESS.

If any item is not SUCCESS, troubleshoot based on the reason field. Adjust the time window and collect diagnostics again if needed.

1. Does CONTAINER_NOT_RUNNING for the real-time thread dump in manifest.json mean that collection failed?

No. This status means that the target container was not running during collection, so a new thread dump could not be generated. In this case, focus on historical automatic thread dumps, docker.log, and events.json. If a real-time thread dump is required, collect diagnostics again when the container is running.

2. Why is fanruan.log or catalina.out missing from the ZIP file?

Common causes include the following: the candidate file does not exist in the container (for example, when the log directory has been changed); the file exists, but no timestamp can be recognized, and the collection item returns APP_LOG_TIMESTAMP_UNRECOGNIZED; or no log records exist in the selected time window. Check the reason field in manifest.json first, and then verify the container log directory and the selected time window.

3. Does [] in events.json mean that collection failed?

No. An empty array means that no persisted Docker events exist for the container in the selected time window. If the event occurred recently, wait for a 60-second reporting cycle and collect diagnostics again. If the status is PERSISTED_EVENT_UNAVAILABLE, the configuration database query failed. Check the connectivity between FineOps and the configuration database.

4. What should I do if docker.log is missing or the status is DOCKER_LOG_UNAVAILABLE?

This status means that the system failed to call the log API of Docker Engine. Check whether the Docker service on the target node and OPS Agent are running. After recovery, collect diagnostics again.

5. Why are there fewer thread dump files than expected?

Only the latest three automatic thread dumps are retained, and only dumps within the selected time window are exported. In addition, if the jcmd command used to collect thread dumps times out after 30 seconds, exits with a non-zero code, or outputs more than 64 MiB, the system does not include truncated content in the package and records only the failure in manifest.json. 

6. Can the system collect the wrong thread dump when multiple Java processes exist in a container?

No. Both real-time and automatic collection first check PID 1. If PID 1 is a Java process, it is used directly. If PID 1 is not a Java process, FineOps collects the thread dump only when it can identify exactly one Java process in the container. Collection is performed through the Docker API in the PID namespace of the target container and is isolated from the host and other project containers.