Topic Browse 0.9.0 Readme

Overview

Allows for browsing and searching for messages on a Kafka Cluster. Deserializes messages into their respective string format and allows for filtering on messages based on their string payload.

Browsing

Messages with payloads of the following types are supported:

  • STRING

  • AVRO

  • JSON_SCHEMA

  • PROTOBUF

JSON Schema and PROTOBUF are supported with Apicurio Schema Registry only.

Filtering

At least one boundary field must be provided per request: fromTimestamp, toTimestamp, partitions, or partitionOffsets.

  • query — case-insensitive substring search across the deserialized key and value payloads

  • fromTimestamp / toTimestamp — restrict messages to a time range (epoch milliseconds); either or both may be specified

  • partitions — restrict browsing to a specific list of partition numbers; combinable with fromTimestamp and/or toTimestamp

  • partitionOffsets — browse a single partition within an explicit offset range (fromOffset, toOffset); mutually exclusive with partitions, fromTimestamp, and toTimestamp

JVM memory

The image sizes the heap at 80% of the container memory limit (-XX:MaxRAMPercentage=80). That suits a deployment with a few GB: the JVM’s non-heap footprint — metaspace, code cache, thread stacks, direct buffers — is broadly fixed rather than proportional, so the heap ceiling plus non-heap still fits.

It does not suit small limits. Below roughly 1.5Gi the same 80% leaves less than the fixed non-heap needs, so the JVM may commit more than the container can hold and the kernel OOMKills it — with no OutOfMemoryError in the log, because the heap itself never exhausts.

Lower the ceiling on such deployments through the chart’s env, which is appended after the image defaults so later -XX flags win:

env:
  - name: JAVA_OPTS
    value: "-XX:MaxRAMPercentage=55 -XX:+UseG1GC -XX:G1PeriodicGCInterval=300000"

MaxRAMPercentage

Pick it so heap + non-heap fits: pct <= (1 - non-heap/limit), minus headroom. Measure non-heap on a running pod as cgroup memory.current minus heap committed.

+UseG1GC

Worth pinning below 1792MiB of container memory, where the JVM otherwise selects SerialGC — which never returns freed memory to the OS, so usage only ratchets upward.

G1PeriodicGCInterval

Lets G1 uncommit while idle; without it G1 only uncommits at Remark and Full GC.

env is a list, so keep any other entries the deployment needs in the same block — a later values layer that sets env replaces it wholesale rather than merging.

Loggers

Below is a per-package breakdown of important packages to help operators configure logging:

Package Logger Description

io.axual.topicbrowse

Root package

io.axual.topicbrowse.consumer

Consumer Service

Kafka consumer lifecycle, partition consumption coordination, and offset management

io.axual.topicbrowse.deserialize

Message Deserialization

Message and header conversion from byte arrays to string representations

io.axual.topicbrowse.deserialize.field.avro

Avro Deserializer

Avro message deserialization

io.axual.topicbrowse.deserialize.field.jsonschema

JSON Schema Deserializer

JSON Schema message deserialization

io.axual.topicbrowse.deserialize.field.masker

Field Masker

Sensitive data masking functionality for JSON payloads

io.axual.topicbrowse.deserialize.field.protobuf

Protobuf Deserializer

Protobuf message deserialization

io.axual.topicbrowse.kafka

Kafka Client Config

Kafka client configuration, authentication strategies (mTLS, SASL/PLAIN, SASL/SCRAM), and SSL setup

io.axual.topicbrowse.validation

Validation Service

Request validation, topic existence checking, and access verification

OpenTelemetry Tracing Configuration

The service uses spring-boot-starter-opentelemetry for distributed tracing.

By default, tracing is enabled with 100% sampling, but OTLP export is disabled.

Enabling Trace Export

To export traces to an OTLP collector (such as Jaeger, Prometheus, or others), configure:

management:
  tracing:
    export:
      enabled: true
  opentelemetry:
    tracing:
      export:
        otlp:
          endpoint: http://otlp-collector:4317  # Replace with your OTLP collector URL
          transport: grpc  # Export protocol: grpc or http/protobuf
          headers: # Custom HTTP headers you want to pass to the collector, for example auth headers.
            key: value

Adjusting Sampling

The trace.sampling.probability property controls the fraction of spans that are collected. Setting it to 1.0 means all spans will be exported.

To adjust the sampling rate (default is 100%):

management:
  tracing:
    sampling:
      probability: 0.1  # 10% sampling

Support for Spring Boot 3.5.x properties

The service has support for Spring Boot 3.5.x OpenTelemetry properties.

You can use the following Spring Boot 3.5.x properties to configure OpenTelemetry:

management:
  tracing:
    enabled: true
  otlp:
    tracing:
      endpoint: http://otlp-collector:4317  # Replace with your OTLP collector URL
      transport: grpc  # Export protocol: grpc or http/protobuf
      headers: # Custom HTTP headers you want to pass to the collector, for example auth headers.
        key: value

The service will map each Spring Boot 3.5.x property to the corresponding Spring Boot 4.x OpenTelemetry property.

Spring Boot 3.5.x property Spring Boot 4.x property Default value

management.tracing.enabled

management.tracing.export.enabled

false

management.otlp.tracing.compression

management.opentelemetry.tracing.export.otlp.compression

"none"

management.otlp.tracing.connect-timeout

management.opentelemetry.tracing.export.otlp.connect-timeout

10s

management.otlp.tracing.endpoint

management.opentelemetry.tracing.export.otlp.endpoint

""

management.otlp.tracing.export.enabled

management.tracing.export.otlp.enabled

true

management.otlp.tracing.headers

management.opentelemetry.tracing.export.otlp.headers

""

management.otlp.tracing.timeout

management.opentelemetry.tracing.export.otlp.timeout

10s

management.otlp.tracing.transport

management.opentelemetry.tracing.export.otlp.transport

"http"