Configure IBM Integration Bus Logging
Configure the Nodinite IBM MQ Monitoring Agent to consume IBM Integration Bus (IIB/ACE) Monitoring Events for end-to-end logging and transaction traceability. On this page, you will learn how to:
✅ 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
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:
- ✅ Installed the IBM MQ Monitoring Agent v7.2.0 or later
- ✅ Created a Monitoring Agent Configuration
- ✅ Configured IBM Integration Bus/ACE to publish Monitoring Events to an IBM MQ queue (see IBM Integration Bus Logging for IIB/ACE setup)
- ✅ Created a Log Agent in Nodinite Administration
- ✅ (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:
The Configuration button opens the remote configuration modal.
Click the Logging tab to access logging configuration:
The Logging tab is located alongside the Monitoring tab in the Remote Configuration modal.
Each log source configuration includes the following tabs:
- Basic - MQ connection details (server, queue manager, source queue, polling interval)
- Authentication - IBM MQ credentials
- Processing - Event mapping and log destination settings (OAuth 2.0/OIDC support)
- Bad Messages - Error handling and backout queue configuration
Add Log Source
Click the Add button to configure a log source for consuming IBM Monitoring Events:
Click 'Add' to create a new log source configuration.
Each log source represents one IBM MQ queue containing Monitoring Events from IBM Integration Bus/ACE.
One accordion per log source entry.
Expand the accordion to configure the log source settings across multiple tabs.
Basic Tab
Configure connection details for the IBM MQ queue containing Monitoring Events.
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 |
| Server | IBM MQ server hostname or IP address | mqserver.example.com |
| Queue Manager | Name of the IBM MQ Queue Manager | QM1 |
| Port | IBM MQ listener port | 1414 (default) |
| Channel | Server connection channel name | SYSTEM.DEF.SVRCONN |
| Source Queue | Queue name containing IBM Monitoring Events | IIB.MONITORING.EVENTS |
| Polling Interval (seconds) | How often to poll for new messages | 30 (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.
Authentication Tab
Configure IBM MQ authentication credentials for accessing the Monitoring Events queue.
Example: Authentication tab for IBM MQ Log Source configuration.
| 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 (Bad Messages tab).
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.
Processing Tab
Configure event processing settings including event mapping and log destination.
Example: Processing tab showing Event Mapping and Log Destination panels.
The Processing tab contains two main configuration panels:
- Event Mapping - Configure how IBM Monitoring Events are mapped to Nodinite logs
- Log Destination - Configure the Nodinite Log API connection and authentication
Event Mapping Panel
Configure Nodinite-specific logging settings to connect this log source to the Nodinite repository.
Event Mapping Settings:
| 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 Panel
Configure the Nodinite Log API connection for secure, authenticated log ingestion.
Log Destination Settings:
| 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.
Example: Log Destination panel 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:
- Configure OpenID Connect in Nodinite v7 - See Install Nodinite - OpenID Connect
- 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.logapiscope) - Add application to Nodinite's allowed clients list
- Configure Log API authentication:
- Check Protected checkbox
- Enter Client ID, Client Secret, Scope, and IDP Token Endpoint
- Save and test - Click Save and verify logs appear in Nodinite
Warning
Token Endpoint URL Format: Use the
/oauth2/v2.0/tokenendpoint for Azure AD v2.0. Legacy/oauth2/tokenendpoints 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 |
Bad Messages Tab
Configure error handling for malformed or unparseable Monitoring Events.
Example: Bad Messages tab for IBM MQ Log Source configuration.
| Field | Description | Example |
|---|---|---|
| Backout Queue Name | Queue name for messages that fail processing (prevents infinite retry loops) | IIB.MONITORING.BADMESSAGES |
Why Bad Message Handling is Critical
- ✅ 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 start logging. Create the queue before saving this configuration.
Common Causes of Bad Messages
- Malformed XML - Monitoring Event structure doesn't match expected schema
- Missing required fields - Event missing MessageFlowName, ApplicationName, or Timestamp
- Encoding issues - Non-UTF-8 characters in payload
- Unsupported event types - Custom Monitoring Event structures not recognized by Nodinite
- 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.
Save Log Source Configuration
Click Save or Save and Close to persist your log source configuration:
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:
- Locate the log source accordion in the Logging tab
- Click the Remove button
- Confirm deletion
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:
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
Configure Message Types:
- Configure Message Types with payload matching rules
- Avoid relying on Default Message Type Name
Set up alerts:
- Create Monitor Views for the backout queue
- Alert on queue depth > 0 to detect processing errors
Review monitoring event structure:
- IBM Integration Bus Logging - Understand event fields and payload structure
Configure queue monitoring:
- Configuration - Monitoring - Set up real-time 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?
- Configure OpenID Connect in Nodinite v7
- Register application in Azure AD/IDP with Client ID and Client Secret
- Edit log source configuration
- Check Protected on the Processing tab (Log Destination panel)
- Enter OAuth credentials (Client ID, Client Secret, Scope, IDP Token Endpoint)
- Save and verify logs still appear
Note
No need to restart the agent - configuration changes apply after next synchronization.
Related Topics
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