- 12 minutes to read

Configure IBM Integration Bus Logging

This page provides step-by-step configuration instructions for consuming IBM Integration Bus (IIB/ACE) Monitoring Events with the Nodinite IBM MQ Monitoring Agent.

On this page:

✅ Add log sources for IBM Monitoring Events
✅ Configure Event Mapping for Nodinite log integration
✅ Set up Log Destination with OAuth 2.0/OIDC authentication
✅ Handle bad messages and processing errors
✅ Optimize polling intervals for performance

Tip

New to IBM Integration Bus logging? First read IBM Integration Bus Logging to understand:

  • Why use the unified agent (vs. legacy standalone agent)
  • ACE vs. IIB version differences
  • Event mapping and Message Type configuration
  • Business searchability best practices

Note

Logging vs. Monitoring: The IBM MQ Agent provides TWO distinct capabilities:

  • Monitoring (see Configuration - Monitoring) - Real-time queue depth, message age, channel status for proactive alerting
  • Logging (this page) - Historical transaction logs from IBM Integration Bus workflows for compliance and business intelligence

Prerequisites

Before configuring logging, ensure you have:

  1. ✅ Installed the IBM MQ Monitoring Agent v7.2.0 or later
  2. ✅ Created a Monitoring Agent Configuration
  3. ✅ Configured IBM Integration Bus/ACE to publish Monitoring Events to an IBM MQ queue (see IBM Integration Bus Logging for IIB/ACE setup)
  4. ✅ Created a Log Agent in Nodinite Administration
  5. ✅ (Optional) Configured OpenID Connect in Nodinite v7 for OAuth 2.0 authentication

Access Logging Configuration

As a Nodinite Administrator, navigate to the IBM MQ agent configuration and click the Configuration button:

Remote Configuration
The Configuration button opens the remote configuration modal.

Click the Logging tab to access logging configuration:

Logging and Monitoring Tabs
The Logging tab is located alongside the Monitoring tab in the Remote Configuration modal.

Each log source configuration includes the following tabs:

  • Basic - Enable/disable log source, display name, and general settings
  • Connection - IBM MQ connection details (server, port, channel, queue manager) and authentication
  • Queues - Queue configuration (source queue, backout queue, polling interval)
  • Processing - Event mapping and log destination settings (OAuth 2.0/OIDC support)

Add Log Source

Click the Add button to configure a log source for consuming IBM Monitoring Events:

Add a Logging Source
Click 'Add' to create a new entry for a Log Source configuration.

Each Log Source represents one IBM MQ queue containing Monitoring Events from IBM Integration Bus/ACE.

Empty Logging Accordion
Each entry is one accordion (log Source).

Expand the accordion to configure the log source settings across multiple tabs.

Basic Tab

Configure general settings for the log source.

Logging Source Basic Tab
Example: Basic tab for IBM MQ Log Source configuration.

Log Source Settings:

Field Description Example
Enable Log Source When checked, consume IBM Monitoring Events from this log source ✅ Checked
Display Name User-friendly name for this log source (appears in logs and diagnostics) IIB Production - QM1

Connection Tab

Configure IBM MQ connection details including server information, authentication, and SSL/TLS settings.

Connection Tab
Example: Connection tab for IBM MQ Log Source configuration.

Connection Settings:

Field Description Example
Server IBM MQ server hostname or IP address mqserver.example.com
Port IBM MQ listener port 1414 (default)
Channel Server connection channel name SYSTEM.DEF.SVRCONN
Queue Manager Name of the IBM MQ Queue Manager QM1

Authentication

The Authentication section is an expandable panel that configures IBM MQ authentication credentials for accessing the Monitoring Events queue.

Logging Authentication Section
Example: Authentication section in Connection tab (expandable panel).

Check the Use Authentication checkbox to enable authentication settings. When enabled, the agent will use the provided credentials to connect to IBM MQ instead of Windows integrated authentication.

Use Authentication Checkbox Example: Use Authentication checkbox to enable IBM MQ credentials.

Field Description Example
Use Authentication When checked, authenticate connection using provided credentials ✅ Checked
Username Username for IBM MQ authentication svc_nodinite
Password Password for IBM MQ authentication ••••••••

Note

The service account must have GET permissions on the Source Queue and PUT permissions on the Backout Queue.

Tip

For Windows environments, you can configure IBM MQ for passthrough authentication using the agent's service account. Leave Use Authentication unchecked to use Windows integrated authentication.

SSL/TLS Settings

Configure secure connections to IBM MQ using SSL/TLS encryption.

Check the Use SSL/TLS checkbox to enable SSL/TLS settings. When enabled, provide the cipher specification and certificate repository details.

Use SSL/TLS Checkbox Example: Use SSL/TLS checkbox to enable secure connection to IBM MQ.

Field Description Example
Use SSL/TLS When checked, use SSL/TLS encryption for the IBM MQ connection ✅ Checked
SSL CipherSpec Select the CipherSpec to use in the SSL conversation TLS_RSA_WITH_AES_256_CBC_SHA256
SSL Key Repository Windows Certificate Store location ("SYSTEM" for system-wide store or "USER" for current user store) SYSTEM

Note

SSL Key Repository Format: Specify the Windows Certificate Store location as either:

  • SYSTEM - for system-wide certificate store
  • USER - for current user's certificate store

For detailed SSL/TLS configuration, consult IBM MQ documentation for secure connection setup.

Queues Tab

Configure queue names and polling settings for IBM MQ log source.

Queues Tab
Example: Queues tab showing source queue, backout queue, and polling interval configuration.

Queue Settings:

Field Description Example
Source Queue Queue name containing IBM Monitoring Events (required) IIB.MONITORING.EVENTS
Backout Queue Queue name for messages that fail processing (required for logging to function) IIB.MONITORING.BADMESSAGES
Polling Interval (seconds) How often to poll the source queue for new messages 60 (range: 30-300)

Polling Interval Considerations

  • Lower values (30-60 seconds): Faster log ingestion, near-real-time visibility, higher MQ load
  • Higher values (120-300 seconds): Reduced MQ load, delayed log visibility, suitable for high-volume environments

Tip

For production environments with high message volume (1000+ events/hour), use 60-120 second polling intervals to balance timeliness and performance.

Why Backout Queue is Required

  • ✅ Prevents log loss - Failed messages are preserved for manual review instead of being discarded
  • ✅ Avoids infinite loops - Malformed messages don't block queue processing
  • ✅ Enables troubleshooting - Review bad messages to identify IIB/ACE configuration issues
  • ✅ Compliance - Retain all data for audit purposes even if unparseable

Backout Queue Setup

Create the backout queue in IBM MQ before enabling logging:

# IBM MQ MQSC commands
DEFINE QLOCAL('IIB.MONITORING.BADMESSAGES') +
  DESCR('Backout queue for unparseable Monitoring Events') +
  MAXDEPTH(5000) +
  DEFPSIST(YES) +
  USAGE(NORMAL)

Warning

Backout Queue Required: If the specified backout queue does not exist, the agent will fail to process messages. Create the queue before saving this configuration.

Common Causes of Bad Messages

  1. Malformed XML - Monitoring Event structure doesn't match expected schema
  2. Missing required fields - Event missing MessageFlowName, ApplicationName, or Timestamp
  3. Encoding issues - Non-UTF-8 characters in payload
  4. Unsupported event types - Custom Monitoring Event structures not recognized by Nodinite
  5. Truncated messages - Messages exceeding MQ maximum message size (default: 4MB)

Tip

Monitoring Bad Messages: Create a Monitor View with a Queue Resource pointing to the backout queue. Set a threshold > 0 to alert when bad messages appear.

Processing Tab

Configure event processing settings including event mapping and log destination.

Processing Tab
Example: Processing tab showing Event Mapping and Log Destination expandable sections.

The Processing tab contains two main configuration sections:

  1. Event Mapping - Configure how IBM Monitoring Events are mapped to Nodinite logs
  2. Log Destination - Configure the Nodinite Log API connection and authentication

Event Mapping

The Event Mapping section is an expandable panel that configures Nodinite-specific logging settings to connect this log source to the Nodinite repository.

Click the Event Mapping header to expand this section.

Event Mapping Section
Example: Event Mapping section expanded showing configuration fields.

Field Description Recommended Value
Log Agent ID Nodinite Log Agent ID for this log source Navigate to Administration > Log Management > Log Agents to find the numeric ID
Default Log Status Code Default status code when not determined from message -1 (auto-detect from event data)
Default Message Type Name Default Message Type if not determined from payload Leave blank; configure Message Types with proper matching rules instead

Message Type Best Practices

  • ❌ Avoid generic names like "Monitoring Event" or "IIB Message"
  • ✅ Use descriptive names like "ACE Order Processing" or "IIB Customer Update"
  • ✅ Configure Message Types with matching rules based on payload structure instead of relying on defaults
  • ✅ Use different log sources for different business domains (e.g., separate log sources for Orders vs. Customers)

Log Status Code Values

Value Behavior Use Case
-1 (Recommended) Auto-detect status from Monitoring Event data IBM Integration Bus reports success/failure via exception list
0 Treat all events as successful unless error indicators present When IIB/ACE is misconfigured and doesn't report exceptions properly

Log Destination

The Log Destination section is an expandable panel that configures the Nodinite Log API connection for secure, authenticated log ingestion.

Click the Log Destination header to expand this section.

Log Destination Section
Example: Log Destination section expanded showing Log API configuration.

Field Description Example
Use Log API When checked, log events are written to the Log Database via the Log API ✅ Checked (recommended)
Log API Base URL Base URL for your Log API endpoint https://nodinite.example.com/LogApi/
Protected When checked, use OAuth 2.0/OIDC (Client Credentials Grant) to authenticate Log API calls ✅ Checked (for secure production environments)

OAuth 2.0 / OIDC Authentication

New 7.2.0

When Protected is checked, the Log API uses OAuth 2.0 Client Credentials Grant for secure authentication. This requires Nodinite v7 with OpenID Connect configured.

Log API with OAuth Protection
Example: Log Destination section with Protected mode enabled showing OAuth 2.0/OIDC fields.

OAuth Configuration Fields:

Field Description Example
Client ID OAuth 2.0 Client ID registered in your Identity Provider (IDP) ibmmq-logging-agent
Client Secret OAuth 2.0 Client Secret for the registered application ••••••••••••••••
Scope OAuth 2.0 scope(s) requested for Log API access nodinite.logapi or api://nodinite-logapi/.default
IDP Token Endpoint OAuth 2.0 token endpoint URL of your Identity Provider https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token

Security Benefits of OAuth 2.0 Mode:

  • ✅ No stored passwords - Uses short-lived access tokens instead of static credentials
  • ✅ Centralized access management - Revoke access via Azure AD/IDP without reconfiguring agents
  • ✅ Audit trail - IDP logs all token requests for compliance
  • ✅ Token rotation - Access tokens expire (typically 60 minutes) and auto-refresh
  • ✅ Service-to-service authentication - Client Credentials Grant designed for unattended services

OAuth Setup Requirements:

  1. Configure OpenID Connect in Nodinite v7 - See Install Nodinite - OpenID Connect
  2. Register application in Identity Provider (IDP):
    • Azure AD: Create App Registration with Client ID and Client Secret
    • Grant API permissions for Nodinite Log API (e.g., nodinite.logapi scope)
    • Add application to Nodinite's allowed clients list
  3. Configure Log API authentication:
    • Check Protected checkbox
    • Enter Client ID, Client Secret, Scope, and IDP Token Endpoint
  4. Save and test - Click Save and verify logs appear in Nodinite

Warning

Token Endpoint URL Format: Use the /oauth2/v2.0/token endpoint for Azure AD v2.0. Legacy /oauth2/token endpoints may not support modern scopes.

Tip

For detailed OAuth setup instructions, see Install Nodinite - OpenID Connect and Log API OAuth Configuration.

When to Use OAuth 2.0 vs. Windows Authentication

Scenario Recommended Mode Reason
Production with Azure AD OAuth 2.0 (Protected) Centralized access management, token rotation, audit trail
Multi-cloud or hybrid environments OAuth 2.0 (Protected) Works across network boundaries without Windows domain trust
On-premises with Active Directory Windows Authentication (Protected unchecked) Simpler setup, leverages existing AD infrastructure
Development/Test environments Windows Authentication Faster setup for local testing
Compliance requirements (SOX, HIPAA) OAuth 2.0 (Protected) Better audit logging and access control granularity

Save Log Source Configuration

Click Save or Save and Close to persist your log source configuration:

Save and Close Buttons
The Save options enable applying configuration changes.

Save - Saves changes and keeps the configuration dialog open for additional edits
Save and Close - Saves changes and closes the configuration dialog
Cancel - Closes the dialog without saving any changes

Note

Synchronization Delay: Configuration changes apply after the next agent synchronization interval (default: 60 seconds). Click the Sync Now button to force immediate synchronization.

Remove Log Source

To delete a log source configuration:

  1. Locate the log source accordion in the Logging tab
  2. Click the Remove button
  3. Confirm deletion

Remove Button
The 'Remove' button deletes the log source configuration from logging.

Warning

Removing a log source does not delete historical logs already ingested into Nodinite. It only stops future log ingestion from this source.

Next Steps

After configuring logging:

  1. Verify log ingestion:

    • Navigate to Home > Log in the Nodinite Web Client
    • Search for logs from the configured Log Agent
    • Verify logs appear within the polling interval

  2. Configure Message Types:

  3. Set up alerts:

    • Create Monitor Views for the backout queue
    • Alert on queue depth > 0 to detect processing errors

  4. Review monitoring event structure:

  5. Configure queue monitoring:

Frequently Asked Questions

Q: Why aren't logs appearing in Nodinite?

Checklist:

  • ✅ Source queue has messages (check queue depth in IBM MQ)
  • ✅ Log Agent ID is correct (verify in Administration > Log Agents)
  • ✅ Log API URL is accessible from the agent server (test with curl/Invoke-WebRequest)
  • ✅ OAuth credentials are valid (check IDP for token request errors)
  • ✅ Agent synchronization completed (check agent diagnostics log for errors)
  • ✅ Polling interval elapsed (wait at least1 polling cycle)

Q: What happens if the Log API is unavailable?

The agent buffers Monitoring Events in memory (up to 1000 messages) and retries delivery every polling interval. If the buffer fills, new messages are moved to the backout queue to prevent data loss.

Q: Can I use the same log source for multiple Integration Nodes?

Yes, as long as all nodes publish to the same IBM MQ queue. However, for better organization and troubleshooting:

  • ✅ Recommended: Create separate log sources per Integration Node/Environment
  • ✅ Use different Source Queues per node (e.g., IIB.NODE1.EVENTS, IIB.NODE2.EVENTS)
  • ✅ Assign different Log Agents per environment (PROD, TEST, DEV)

Q: How do I switch from Windows Authentication to OAuth 2.0?

  1. Configure OpenID Connect in Nodinite v7
  2. Register application in Azure AD/IDP with Client ID and Client Secret
  3. Edit log source configuration
  4. Check Protected on the Processing tab (Log Destination panel)
  5. Enter OAuth credentials (Client ID, Client Secret, Scope, IDP Token Endpoint)
  6. Save and verify logs still appear

Note

No need to restart the agent - configuration changes apply after next synchronization.

Configuration - Monitoring – Set up real-time queue monitoring
IBM MQ Agent Configuration Hub – Overview of Settings, Monitoring, and Logging
IBM Integration Bus Logging – IIB/ACE Monitoring Profile setup and concepts
Message Types – Configure payload matching and classification
Log Agents – Manage Log Agent configurations
Install Nodinite - OpenID Connect – OAuth 2.0/OIDC setup guide
Install IBM MQ Monitoring Agent
Update
Troubleshooting