Troubleshoot integration

Here are some common issues and their troubleshooting steps for the API hub connector integration.

API metadata does not show up in API hub

• Initial sync time: It can take a few hours for the initial synchronization to start and for API data to appear in API Hub. It is recommended to wait for a few hours.
• Plugin instance status: Verify that the Plugin instance in API hub has not been deleted or changed.
• Gateway ID: Ensure the correct Gateway ID is configured properly in your Apigee Edge for Private Cloud API hub connector settings.
• Check logs: Check if there is any error logged in Edge for Private Cloud API hub connector service logs /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log.

Proxy deployed but information in API hub is not accurate

• Propagation Delay: Allow a few minutes for deployed proxy information to propagate and be reflected in API hub.
• Check logs: Review the Edge for Private Cloud API hub connector logs for details on uploaded proxies. This can help identify if the proxy update was successfully processed for synchronization.

User organization stopped syncing without changing anything in API hub connector

• Plugin instance status (API hub side): Verify if the associated plugin instance in API hub has been deprovisioned, deleted, or altered. Any changes on the API hub side can directly impact synchronization from the API hub connector.
• Check logs: Review the Edge for Private Cloud API hub connector logs for any errors, warnings, or issues that might indicate a disruption in the synchronization process. This could include connectivity issues or authentication problems with API hub.

Using the status API (Recommended for opted-in organizations):

The status API provides a direct way to see which organizations have opted in and are actively synchronizing.

Log based troubleshooting

Where are the API hub connector logs stored?

/opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log

How do I get information about the orgs that are enabled?

To determine which organizations (orgs) are currently enabled and being synchronized, you can leverage the status API and inspect the system logs.

• Action: Call the status API endpoint.
• Expected output: Opted-in organizations will be listed under the apiSyncStatus and analyticsSyncStatus sections within the API response. Orgs with Metadata sync enabled will show up under apiSyncStatus and Orgs with runtime sync enabled will show up under analyticsSyncStatus.

  {
   "apiSyncStatus": [
     {
       "organization": "foo",
       "phase": "Preparing", // ColdTransfer => Preparing
       "components": [
         "proxy": {
           "lastUpdated": "2025-04-16T00:56:45Z",
           "progress": {
             "totalItems": 100, // total proxies known to uapim connector
             "pendingItems": 90,  // pending proxies to upload
             "completedItems": 6, // completed proxies to upload
             "failedItems": 4 // proxies failed to upload
           }
         },
         "environment": { //environment upload status
           "lastUpdated": "2025-04-16T00:56:45Z",
           "progress": {
             "totalItems": 5, // total number of environments
             "pendingItems": 1, // pending environments to process
             "completedItems": 3, // completed environment processing
             "failedItems": 1 // failed environment processing
           }
         }]
     },
     {
       "organization": "bar",
       "phase": "Processing", // "Streaming" -> "Processing"
       "components": [
         "proxy": {
           "lastUpdated": "2025-04-16T00:56:45Z",
           "progress": {
             "totalItems": 110, // total proxies known to uapim connector
             "pendingItems": 16, // pending proxies to upload
             "completedItems": 3, // completed proxies to upload
             "failedItems": 1 // proxies failed to upload
           }
         },
         "environment": {
           "lastUpdated": "2025-04-16T00:56:45Z",
           "progress": {
             "totalItems": 5, // total number of environments
             "pendingItems": 3, // pending environments to process
             "completedItems": 1, // completed environment processing
             "failedItems": 1 // failed environment processing
           }
         }]
     },
     {
       "organization": "test",
       "phase": "Queued", // "Yet to start" -> "Queued"
       "lastUpdated": "2025-04-16T00:56:45Z"
     }
   ],
   "analyticsSyncStatus": [
     {
       "organization": "test",
       "environment": "dev",
       "failedItems": 2,
       "lastUpdated": "2025-04-16T00:56:45Z"
     },
     {
       "organization": "test",
       "environment": "prod",
       "failedItems": 4,
       "lastUpdated": "2025-04-16T00:56:45Z"
     }
   ]
  }
  

• Inspecting system logs: For a more granular view and to confirm the setup of synchronization for individual organizations, you can examine the system logs for specific entries.
  • Check logs:

    /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log

  • Search commands: Use grep or similar log searching tools to find the following log lines:
    • For metadata synchronization of org metadata-org:

      grep "Setup metadata sync for organization: metadata-org"  /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log

    • Example log snippet:

      2025-07-10 08:47:09,901  main INFO  c.a.u.c.UAPIMConnectorServiceImpl - UAPIMConnectorServiceImpl.setupMetadataSync() : Setup metadata sync for organization: metadata-org

    • Look for the text Setup metadata sync for organization: followed by the organization name.
    • For runtime data synchronization of org runtime-org:

      grep "Setup runtime data sync for organization: runtime-org" /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log

    • Example log snippet:

      2025-07-10 08:47:09,902  main INFO  c.a.u.c.UAPIMConnectorServiceImpl - UAPIMConnectorServiceImpl.setupRuntimeSyncData() : Setup runtime data sync for organization: runtime-org

    • Look for the text Setup runtime data sync for organization: followed by the organization name.

How do I get information of all the (org,env) that failed to be enabled from logs?

To get information about organizations that failed to be enabled, you can examine the system logs for specific error entries.

• Check logs: /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log
• Search commands: Use grep or similar log searching tools to find log lines indicating an error during the metadata sync status update.
  • For failed metadata synchronization status updates for org/env failed-org/failed-env:

    grep "Error while updating metadata sync status for org: failed-org" /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log

  • Example log snippet:

    2025-07-15 10:30:15,123 main ERROR c.a.u.c.UAPIMConnectorServiceImpl - UAPIMConnectorServiceImpl.updateMetadataSyncStatus() : Error while updating metadata sync status for org: failed-org

  • Look for the text Error while updating metadata sync status for org/env: followed by the organization and environment (for example, failed-org/failed-env).

How can I get a summary of the transfer state change of org from logs?

To get a summary of when an (org, env) synchronization transfer state is updated, you can examine the system logs for specific entries.

• Check logs: /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log
• Search commands Use grep or similar log searching tools to find log lines indicating an update to the transfer status for an organization and environment.
  • For transfer status updates:

    grep "Transfer status is updated for org" /opt/apigee/var/log/edge-uapim-connector/edge-uapim-connector.log

  • Example log snippet:

    2025-07-15 18:35:01,789 main INFO c.a.u.c.UAPIMConnectorServiceImpl - UAPIMConnectorServiceImpl.updateTransferStatus() : Transfer status is updated for org: org1 to BULK_TRANSFER
    2025-07-10 08:47:11,364  main INFO  c.a.u.m.UAPIMMetadataServiceImpl - UAPIMMetadataServiceImpl.updateEnvironmentStatus() : Transfer status is updated for org: org1 to STREAMING

  • Look for the exact text "Transfer status is updated for org/env" followed by the specific organization and environment (e.g., org1/prod) and the state.