NOTE: Documentation is still very much WIP, please feel free to contribute.

This will be a short guide on how to develop your own CodeCTRL-compatible logger, using the official Rust logger as an example.

Table of Contents
Requirements
What is needed to implement
Basic logging functions
Batch logging functions
Connecting to CodeCTRL

Requirements

You will most likely need the following requirements if you intend to develop your own CodeCTRL-compatible logger.

• The protobuf compiler — protoc.
  • Usually available in package managers. For example in Fedora: # dnf install protobuf-compiler.
• A local copy of the CodeCTRL protobuf files available here.

What is needed to implement?

You will need to implement the following services to be fully compatible with CodeCTRL versions 1.0.0-beta and later:

• The LogServer and LogClient services detailed in the cc_server.proto file.
• The Authentication service detailed in the auth.proto file.

Basic logging functions

Language loggers should aim to keep inline with the consistent API across CodeCTRL language loggers described in the following table:

Function name1	Parameters	Description
log	message : T | string surround (optional) : u32 host (optional) : string port (optional) : string	The most basic log function.
log_if	condition : fn() -> bool message : T | string surround (optional) : u32 host (optional) : string port (optional) : string	Logs only if the given condition function/closure/lambda returns true.
log_when_env	message : T | string surround (optional) : u32 host (optional) : string port (optional) : string	Logs only if the CODECTRL_DEBUG environment variable is present.

Batch logging functions

Additionally, the API should provide the ability to “batch” logs together, i.e. generate multiple logs and send all at once. This is done via the LogBatch type in the Rust logger, and similar approaches should be used when implementing loggers for other languages.

The purpose of the batch send functionality to allow users of the libraries to choose when the right time is to send the logs, especially in environments where predictable timings are necessary.

In addition, it would be useful if the users of the logger had the ability to set the host and port for the entire batch, which could be done during the creation of the object or as methods on the object which modify the internal values.

Function name1	Parameters	Description
LogBatch.add_log	message : T | string surround (optional) : u32	Add a basic log to the LogBatch.
LogBatch.add_log_if	condition : fn() -> bool message : T | string surround (optional) : u32	Adds the log to the LogBatch only if the condition function/closure/ lambda returns true.
LogBatch.add_log_when_env	message : T | string surround (optional) : u32	Adds the log to the LogBatch only if the CODECTRL_DEBUG environment variable is present.

Connecting to CodeCTRL

CodeCTRL uses gRPC for both internal and external communication. To get started with gRPC for your language, consult the gRPC documentation first to see if they have already provided a library for your language that you can use to communicate with CodeCTRL.

This is where the protobuf files mentioned earlier are used, as they contain the basic skeleton of how the logger should communicate with the gRPC server behind CodeCTRL. Loggers need only implement the LogClient service (authorisation and authentication is still being worked on).

---

1: The function names in the language API do not need to be in snake_case, follow the style officially used by the language. For example, in C# use PascalCase and camelCase.