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.

Stage	Key	Notes
1. Connector collect inbound data	INBOUND_1
2. Connector assemble inbound message	INBOUND_2
3. Connector transfer inbound message	INBOUND_3
4. Platform receive inbound message	INBOUND_4	For platform use only
5. Platform store inbound message	INBOUND_5	For platform use only
6. Platform generate outbound message(s)	OUTBOUND_1	For platform use only
7. Connector receive outbound message	OUTBOUND_2
8. Connector assemble outbound data	OUTBOUND_3
9. Connector deliver outbound data	OUTBOUND_4
10. Platform finalise outbound delivery	OUTBOUND_5	For 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.

Level	Code	Description
INFO	N	Informational messages (INFO)
WARNING	W	Messages requiring immediate attention
ERROR	E	Messages 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 Range	Category	Description
1000-1999	Data	Retrieving or storing data
2000-2999	Logic	Business logic or data transformation
3000-3999	Filter	Filtering messages
4000-4999	Contact	Communicating with an external system
5000-5999	Exchange	Sending or receiving messages
0000	Internal Server Issue	Fallback "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.

Code	Level	Description
1000N	INFO	Data saved
1000W	WARNING	Could not save data
1001E	ERROR	Data rejected by external system
1001W	WARNING	Key data is missing
1002E	ERROR	Key data is missing
2000N	INFO	Message created
2001E	ERROR	Bad data received from external system
3000N	INFO	Message filtered
3001N	INFO	Message skipped
3002E	ERROR	Invalid filter
4000N	INFO	Authenticated with SyncHive
4001N	INFO	Authenticated with external system
4002E	ERROR	Could not reach SyncHive
4003W	WARNING	Could not reach external system
4004W	WARNING	Rate Limit Exceeded
4003E	ERROR	Could not reach external system
4004E	ERROR	Authentication to SyncHive failed
4005E	ERROR	Authentication to external system failed
5000N	INFO	Message sent
5001N	INFO	Message received
5002E	ERROR	SyncHive rejected the message
5003E	ERROR	Data rejected by external system
5003N	INFO	Data polled
5004N	INFO	Data received
5005N	INFO	Data sent
0000E	ERROR	Error
0000W	WARNING	Warning

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.",
  "shapeName": "Product",
  "mode": "LIVE",
  "generatedAt": "2024-05-03 17:30:00.895 +1200"
}

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

  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"
}