feat: added timestamp rfc3339 format with nanoseconds

[edge33]

✨ Feature: Support RFC 3339 Timestamps with Nanosecond Precision

This update introduces support for RFC 3339-formatted timestamps with nanosecond precision, enabling higher-resolution time tracking for logs—especially useful in distributed systems, observability pipelines, and time-sensitive applications.

🔍 Background

Pino’s default timestamp format is optimized for performance and compactness, typically using Date.now() or epochTime in milliseconds. However, modern observability stacks and structured logging systems (e.g., OpenTelemetry, Loki, or JSON-based pipelines) often require nanosecond precision and ISO 8601-compliant timestamp formats.

The need for increased timestamp precision arose from observing that log entries occasionally appeared out of order in Google Cloud Logging. This was due to multiple entries sharing the same millisecond timestamp, resulting in collisions. By adopting nanosecond-level precision, we significantly reduce the likelihood of these collisions and preserve the correct log order. The performance overhead of formatting timestamps with nanosecond precision is negligible.

✅ What’s New

New timestamp function: pino.timestamp.isoTimeNanos

Outputs timestamps in RFC 3339 format with nanosecond precision, e.g.:

2025-08-02T14:36:12.123456789Z

Built using process.hrtime.bigint() to ensure monotonic and high-resolution timing

Compatible with pino.transport() and all core Pino features

🔧 Usage

const pino = require('pino')

const logger = pino({
  timestamp: pino.timestamp.isoTimeNanos
})

logger.info('High-resolution log timestamp')

📈 Use Cases
Distributed tracing and telemetry

Scientific or financial applications requiring precise time tracking

Compatibility with logging systems expecting strict RFC 3339 formats

⚠️ Notes
Nanosecond precision is only available in Node.js versions that support process.hrtime.bigint().

Minor overhead may be introduced due to the additional precision formatting.

🧪 Testing
Thorough tests have been added to validate:

Correct formatting of timestamps

Monotonic behavior

🚀 Performance

Benchmarking was done using the following script:

// Default pino ISO timestamp (RFC 3339 with millisecond precision)
const defaultTimestamp = () => `,"time":"${new Date(Date.now()).toISOString()}"` // using Date.now() for testability
const startHRTimeNs = process.hrtime.bigint()
const startWallTimeNs = BigInt(Date.now()) * 1_000_000n

const MS_MULTIPLIER = 1000
const NS_DIVISOR = 1_000_000_000n

// Custom RFC 3339 with fake nanosecond precision
function customNanosecondTimestamp () {
  const totalNs = startWallTimeNs + (process.hrtime.bigint() - startHRTimeNs)
  const iso = new Date(
    Number(totalNs / NS_DIVISOR) * MS_MULTIPLIER
  ).toISOString()

  return `,"time":"${iso.slice(0, 19)}.${(totalNs % NS_DIVISOR)
    .toString()
    .padStart(9, '0')}Z"`
}

// Benchmarking utility
function benchmark (fn, label, iterations = 100000) {
  const start = process.hrtime.bigint()
  for (let i = 0; i < iterations; i++) {
    fn()
  }
  const end = process.hrtime.bigint()
  const durationMs = Number(end - start) / 1e6
  console.log(`${label}: ${durationMs.toFixed(2)} ms for ${iterations} runs`)
}

// Run benchmarks
const iterations = 1_000_000
console.log(`Benchmarking ${iterations} iterations...`)
benchmark(defaultTimestamp, 'Default Pino timestamp', iterations)
benchmark(customNanosecondTimestamp, 'Custom nanosecond timestamp', iterations)

outcome:

Benchmarking 1000000 iterations...
Default Pino timestamp: 420.57 ms for 1000000 runs
Custom nanosecond timestamp: 465.04 ms for 1000000 runs

[simoneb]

LGTM, nice addition 🚀

[mcollina]

Also docs are missing

[mcollina]

Can you avoid this top level changes? This would make the test unmaintanable.

[simoneb]

they're run in isolation though, aren't they?

[mcollina]

Yes, but this file is structured to contain multiple tests anyway (via test) and if you look there is also some duplicated logic inside.

[edge33]

I moved the mocking logic inside the test, the logic duplication is driven by the need of returning two different values in order to compute the timestamp, it simulates time passing. Also, the fact that I need to store the value of process.hrtime.bigint() when the app starts, requires the mocked function to be created before the module is required, hence the need of importing the module inside the test function. I'm open to different approach if you have ideas here

[mcollina]

Please update the types tests too

[mcollina]

lgtm

[jsumners]

The precision is "nanosecond." Also, please review linting and testing errors.

[toomuchdesign]

Dropping here a debatable idea to make this test a bit more explicit.

test('pino.stdTimeFunctions.isoTimeNanos returns RFC 3339 timestamps', async ({ equal }) => {
  // Mock Date.now at module initialization time
  const now = Date.now
  Date.now = () => new Date('2025-08-01T15:03:45.000000000Z').getTime()

  // Mock process.hrtime.bigint at module initialization time
  const hrTimeBigint = process.hrtime.bigint
  process.hrtime.bigint = () => 100000000000000n

  const pino = require('../')

  const opts = {
    timestamp: pino.stdTimeFunctions.isoTimeNanos
  }
  const stream = sink()

  // Mock process.hrtime.bigint at invocation time
  process.hrtime.bigint = () => 100000000000000n + 12345678n

  const instance = pino(opts, stream)
  instance.info('foobar')
  const result = await once(stream, 'data')

  equal(result.hasOwnProperty('time'), true)
  equal(result.time, '2025-08-01T15:03:45.012345678Z')

  Date.now = now
  process.hrtime.bigint = hrTimeBigint
})

[edge33]

refactored the function to squeeze more performance out of it, latest benchmark run:

Benchmarking 1000000 iterations...
Default Pino timestamp: 447.21 ms for 1000000 runs
Custom nanosecond timestamp: 232.79 ms for 1000000 runs

[edge33]

@jsumners sorry for the ping 🙏 , but this PR has been pending for a month now, can I get a new review when you have the chance? :)