Skip to main content

Logging

SyncHive captures log messages throughout the entire message lifecycle, from receiving the data from an application to sending data to another application. These logs are crucial for end users, enabling them to diagnose and address issues efficiently within SyncHive. It's essential for Connector developers to ensure comprehensive logging, giving end users a clear view of the message's journey.

Constructing a Log Message

When constructing a log message payload, there are several key concepts to learn:

Lifecycle Stage

A lifecycle stage indicates a particular moment in the SyncHive message lifecycle. When sending a log message, you must specify the corresponding stage within the message lifecycle.

StageKeyNotes
1. Connector collect inbound dataINBOUND_1
2. Connector assemble inbound messageINBOUND_2
3. Connector transfer inbound messageINBOUND_3
4. Platform receive inbound messageINBOUND_4For platform use only
5. Platform store inbound messageINBOUND_5For platform use only
6. Platform generate outbound message(s)OUTBOUND_1For platform use only
7. Connector receive outbound messageOUTBOUND_2
8. Connector assemble outbound dataOUTBOUND_3
9. Connector deliver outbound dataOUTBOUND_4
10. Platform finalize outbound deliveryOUTBOUND_5For platform use only

Log Level

Log messages are classified into three levels. Choose the appropriate level that aligns with the significance of your log message.

LevelCodeDescription
INFONInformational messages (INFO)
WARNINGWMessages requiring immediate attention
ERROREMessages indicating critical failures that require immediate action

Log Code

Log codes are alphanumeric representations of the content within a log message. These codes are logically organized into distinct ranges.

Log Code Range

Code RangeCategoryDescription
1000-1999DataRetrieving or storing data
2000-2999LogicBusiness logic or data transformation
3000-3999FilterFiltering messages
4000-4999ContactCommunicating with an external system
5000-5999ExchangeSending or receiving messages
0000Internal Server IssueFallback "catch-all" codes for unexpected issues

Log Code Glossary

Refer to the glossary below to select an appropriate log code when creating your log message. Note that a suffix of the log level is appended to the code.

CodeLevelDescription
1000NINFOData saved
1000WWARNINGCould not save data
1001EERRORData rejected by external system
1001WWARNINGKey data is missing
1002EERRORKey data is missing
1003EERRORDuplicate data ID
1004EERRORInvalid message
1004WWARNINGInvalid message
2000NINFOMessage created
2001EERRORBad data received from external system
3000NINFOMessage filtered
3001NINFOMessage skipped
3002EERRORInvalid filter
4000NINFOAuthenticated with SyncHive
4001NINFOAuthenticated with external system
4002EERRORCould not reach SyncHive
4003WWARNINGCould not reach external system
4003EERRORCould not reach external system
4004EERRORAuthentication to SyncHive failed
4004WWARNINGRate Limit Exceeded
4005EERRORAuthentication to external system failed
5000NINFOMessage sent
5001NINFOMessage received
5002EERRORSyncHive rejected the message
5003EERRORData rejected by external system
5003NINFOData polled
5004NINFOData received
5005NINFOData sent
5006WWARNINGUnauthorized
5006EERRORUnauthorized
5007WWARNINGConnector unavailable
5007EERRORConnector unavailable
5008WWARNINGPlatform unavailable
5008EERRORPlatform unavailable
0000EERRORError
0000WWARNINGWarning

Correlation ID

The correlation ID is crucial for maintaining traceability of logs and messages in SyncHive. The platform uses the correlation ID on messages received for logging. To ensure that the logs are linked together, the same correlation ID must be used when logging in the connector.

See more: Correlation ID

Writing a Clear and Informative Log Message

When composing the contents of a log message, prioritize clarity and relevance for the end-user. To ensure readability and prompt action, we recommend structuring your log message content as follows:

  • What went wrong?: Clearly state the issue or error that occurred.
  • Why did it go wrong?: Provide insight into the reason or cause behind the issue.
  • What can you do about it?: Offer actionable steps or suggestions for addressing the problem.

Adapt this structure for warning and informational log messages as needed.

Following this approach will help ensure that log messages effectively convey information and empower users to respond appropriately.

When to Send a Log Message

When it comes to logging, finding the right balance is key. Too little logging can leave the end user struggling to diagnose issues due to a lack of context. On the other hand, too much logging can overwhelm users with an excess of information, making it difficult to pinpoint the root cause of problems. To help guide your logging practices, we recommend logging SyncHive messages in the following scenarios:

Informational Messages (INFO): For informative messages, consider logging the following lifecycle stages:

  • 3. Connector transfer inbound message
  • 7. Connector receive outbound message
  • 9. Connector deliver outbound data

Warning Messages: When logging warnings, it's advisable to log the following lifecycle stages:

  • 3. Connector transfer inbound message
  • 9. Connector deliver outbound data

Error Messages: In the case of errors, it's best to log every single Connector lifecycle stage to ensure thorough logging and diagnosis:

  • 1. Connector collect inbound data
  • 2. Connector assemble inbound message
  • 3. Connector transfer inbound message
  • 7. Connector receive outbound message
  • 8. Connector assemble outbound data
  • 9. Connector deliver outbound data

Sending a Log Message

To send a log message to SyncHive, create a payload according to the schema below and call the following API:

PUThttps://{synchive_api_url}/data-service/v1/message
Headers
limber-connector: "{synchive_connector_key}"
Content-Type: "application/json"
Body
{
"code": "4005E",
"level": "ERROR",
"lifeCycleStage": "OUTBOUND_4",
"detail":
"Could not connect to ShopifyNZ.

The HTTP API Key Value you provided is incorrect.

Please provide a valid HTTP API Key Value to the ShopifyNZ Integration and try again.",
"integrationKey": "ShopifyNZ",
"shapeName": "Product",
"mode": "LIVE",
"generatedAt": "2024-05-03 17:30:00.895 +1200",
"correlationId": "14cac731-6dd7-424c-bfbf-f0be0b07f8cf"
}
Schema
{
code: string,
// Required
// A code that describes the contents of this log message

level: string,
// Required
// Message level
// Enum: [ ERROR, WARNING, INFO, DEBUG ]

lifeCycleStage: string,
// Required
// Life cycle stage that produced the log message
// Enum: [ INBOUND_1, INBOUND_2, INBOUND_3, INBOUND_4, INBOUND_5, OUTBOUND_1, OUTBOUND_2, OUTBOUND_3, OUTBOUND_4, OUTBOUND_5 ]

detail: string,
// Required
// maxLength: 3000
// Human readable data log detail. Stored as Markdown

integrationKey: string,
// Required
// Source Integration for the log message

shapeName: string,
// Required
// Shape of the data

mode: string,
// Required
// Mode of operation
// Enum: [ SANDBOX, LIVE ]

generatedAt: string,
// Required
// The date and time with an offset from UTC, represented as a string in the ISO 8601 format.
// Example: "2024-05-03 17:30:00.895 +1200"

correlationId: string,
// Required
// Correlation ID for related message tracing
}