BitLogger/docs/api/field.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
field	api	record	20260512	Create a single structured field value from a key and value pair.	field record helper public

Field

Create a single Field value from a key and value pair. This is the basic helper used throughout logger, patch, and filter APIs whenever structured metadata needs to be attached to a record.

Interface

pub fn field(key : String, value : String) -> Field {}

input

• key : String - Field key name.
• value : String - Field value text.

output

• Field - Structured field value ready to be used in a record or field array.

Explanation

Detailed rules explaining key parameters and behaviors

• The helper constructs a Field directly from the provided key and value.
• No deduplication, normalization, or validation is applied.
• This is the standard primitive used by fields(...), append_fields(...), and all log write APIs that accept structured fields.
• The created field preserves the original input strings exactly.

How to Use

Here are some specific examples provided.

When Add One Inline Event Field

When a single structured field is enough:

logger.info("accepted", fields=[field("user", "alice")])

In this example, the event carries one explicit structured attribute.

When Build Shared Context Fields

When binding one reusable metadata field to a logger:

let logger = Logger::new(console_sink(), target="audit")
  .bind([field("service", "billing")])

In this example, the field becomes part of every later emitted record.

Error Case

e.g.:

• If key is empty, the resulting field still exists and keeps the empty string key.

• If value is empty, the field remains valid and simply stores an empty string value.

Notes

1. Use this helper when only one field is needed and tuple syntax would be less direct.

2. Prefer stable field keys so filters and downstream tooling remain predictable.