Odyssey Manager Monitoring and Troubleshooting

This article covers how to tell the Odyssey Manager service is healthy, where it logs, and what the most common problems point to. For configuration, see the Odyssey Manager Administrator Guide.

Is Odyssey Manager running? (heartbeat)

A heartbeat is a periodic "I'm still running" signal a service writes so you can tell it's alive. Every outbound poll pass, Odyssey Manager writes one to the ILLiad SystemInformation table under Source = Odyssey Manager:

Field	Value	When
Status	Running	Start of each pass
Last Run	current time	Start of each pass
Status	Idle	End of each pass
Next Run	current time + OutboundPollIntervalSeconds	End of each pass

To confirm the service is running, look for a recent Last Run timestamp on the Odyssey Manager source. (The heartbeat writes are best-effort — a failure is logged but never blocks a pass.)

Logs

Logging is configured through ILLiadOdysseyManager.log.config (log4net):

Destination	Levels	Notes
logs/ILLiadOdysseyManager.log	INFO and above	Rolling: up to 10 backups of 10 MB each.
logs/ILLiadOdysseyManager-Errors.log	ERROR–FATAL	Errors only.
Windows Event Log ("ILLiad Odyssey Manager")	ERROR–FATAL	Errors and above also surface here.

Every log line carries a [documentId] tag, so you can follow one document all the way through a pass. To trace one document, or view recent errors:

Select-String -Path "logs\ILLiadOdysseyManager.log" -Pattern "\[<documentId>\]"
Get-Content -Tail 200 logs\ILLiadOdysseyManager-Errors.log

Running with --console adds console logging on top of the file log.

Access-control logging

Odyssey Manager keeps an audit trail of every inbound TCP connection — both accepted and denied — so administrators can review who connected to the Odyssey listener. This carries forward from the Delphi Odyssey Manager.

Common problems

Symptom	Where to look
Service won't start	The Event Log source "ILLiad Odyssey Manager". Usual causes: a missing or unwritable DataPath, an invalid OdysseyManager config section (the service prints the failing setting), or an unreachable logon database.
Service runs but no heartbeat	No SystemInformation rows for Odyssey Manager means the outbound worker isn't completing a pass — check the errors log for a database or startup error.
Inbound peers temporarily rejected	The concurrency cap was reached. Review MaxConcurrentProcessing; sustained rejection may mean a document is stuck — find its documentId in the log.
Document marked "Unrecognized file type"	The automatic path accepts only application/tiff, application/tif, or application/pdf. A sender using image/tiff or another type is rejected by design.
Document marked "Empty File"	A zero-byte inbound file — the sender delivered no content.
Delivery fails with "PDF Conversion Failed"	Usually WebPDFPath isn't set for the NVTGC, or the source file didn't resolve inside a permitted inbound directory.
Delivered PDF has no cover sheet	Neither cover-sheet key pair is configured for the NVTGC and the legacy fallback file doesn't exist. Set the cover-sheet keys.
Article Exchange uploads fail authentication	One or more of the four OCLC credential keys is empty at the parent site. Set all four.
Transactions deliver but no billing is written	Confirm the gate key (BillingActiveLending or BillingActiveDocDel) is on, the billing category isn't Exempt, and no billing rows already exist (the already-billed guard skips a re-run).
OCR expected but didn't run	OCR fires only when ArticleExchangeOCREnabled is on for the receiving site and the merged PDF has at least one image-only page. A fully searchable PDF is delivered as-is.