open-telemetry / open-telemetry/opentelemetry-php

Wrap PSR-20 clock

Open
#2,042 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
PHP
Stars
912
Forks
232
Avg merge
7d 16h
Merged PRs (30d)
4

Description

Is your feature request related to a problem?
Our application defines a PSR-20 Clock and wants all dependent "current time" to be based off of it.
I'm aware that opentelemetry requires nanosecond precision which PSR-20 does not define.
However the SystemClock current implementation does 2 things:

  1. Get a reference time using microtime() + hrtime()
  2. Compute a current time using this reference time and a new call to hrtime().

Describe the solution you'd like
I'd love to see a bundled clock (we currently just implement our own) that looks like this:

<?php

declare(strict_types=1);

namespace collecthor\components;

use DateTimeImmutable;
use OpenTelemetry\API\Common\Time\ClockInterface as OtelClockInterface;
use Psr\Clock\ClockInterface;

final class OtelClock implements OtelClockInterface
{
    private readonly int $referenceTime;

    public function __construct(DateTimeImmutable|ClockInterface $reference)
    {
        $now = $reference instanceof ClockInterface ? $reference->now() : $reference;
        $this->referenceTime = $now->getTimestamp() * OtelClockInterface::NANOS_PER_SECOND
            + (int) $now->format('u') * OtelClockInterface::NANOS_PER_MICROSECOND;
    }

    public function now(): int
    {
        return $this->referenceTime + hrtime(true);
    }
}


One of the goals of PSR-20 is to make a dependency on time explicit. This solution provides that benefit while still conforming to the requirements of opentelemetry of nanosecond precision.

Additional context
This is not a duplicate of https://github.com/open-telemetry/opentelemetry-php/issues/950.

Tip: React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the existing SystemClock implementation and its current-time integration points, then compare them with the proposed PSR-20-compatible clock shape. Done means a bundled clock can use a DateTimeImmutable or PSR-20 ClockInterface as its reference while retaining the nanosecond precision required by OpenTelemetry.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
observability
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.