Table of Contents

• Introduction
• Installation
• Usage
  • Initialization
  • Logging Messages
  • Querying Log Entries
  • Database Schema
• Author
• Contributing
• Licensing

Introduction

Kataposis (or ktpss) is a logging library for Go that provides a simple but effective logging mechanism, seemlessly saving entries to a database. It provides a fluent API for constructing and storing log entries in the database, and it also supports fetching log entries based on various criteria.

At the moment, supported databases include Postgres. Kataposis currently supports the basic log parameters such as message, log level, timestamp, and resource ID; with a design that allows for easy support for more parameters as needed in the future.

Installation

First step towards using Kataposis in your Go application is to add the module to your Go program:

go get -u cheezaram.tech/kataposis

Usage

Initialization

To initialize Kataposis and set up the database connection, use the Init function along with optional configuration options:

package main

import (
	"time"

	"cheezaram.tech/kataposis"
)

func main() {
	var err error
	// Initialize the logger.
	log, err := kataposis.Init(
		kataposis.WithPGAddr("localhost:5432"),
		kataposis.WithPGDB("kataposis"),
		kataposis.WithPGUser("kataposis"),
		kataposis.WithPGPassword("kataposis"),
	)

	if err != nil {
		// Handle error
	}
}

Logging Messages

Use the fluent API provided by Kataposis to create log entries and save them to the database:

func main() {
	// Previous initialization code.

	// Log a message.
	err = log.Msg("Log message").RID("1234").Level("info").Timestamp(time.Now())
	if err != nil {
		// Handle error
	}
}

Querying Log Entries

You can fetch log entries from the database based on specific criteria using the Fetch method:

func main() {
	// Previous initialization code.

	afterTime := time.Now()
	entries, err := log.Fetch(
		"message",  // Message
		"1234",     // Resource ID
		"",         // Log level. Will not be included in the query condition.
		nil,        // Before timestamp. Will not be included in the query condition.
		&afterTime, // After timestamp
	)

	if err != nil {
		// Handle error
	}

	// Process fetched log entries
	for _, entry := range entries {
		// Do something with each log entry
		fmt.Printf("Message: %s, Timestamp: %s\n", entry.GetMsg(), entry.GetTimestamp())
	}
}

You can retrieve the value of each field using the methods of the kataposis.LogEntry struct, usually prefixed with Get.

NB: If any argument is set to its default value during fetching, the argument will not be included in the query condition.

Database Schema

Kataposis creates a table named logs in the specified database with the following schema:

CREATE TABLE IF NOT EXISTS logs (
    id SERIAL PRIMARY KEY,
    rid TEXT,
    message TEXT,
    level TEXT,
    timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Author

This library was written by Chee-zaram Okeke with love. Feel free to connect.

Contributing

If you find any bugs, feel free to open an issue. Pull request for new features or bug fixes are welcome.

After commiting your changes, run the utils/contributors.sh script to add yourself to the contributors list.

See CONTRIBUTORS for details of all contributors.

Licensing

See LICENSE for details.