Describe your environment

The docker-compose.yaml file in this repo, running on a MacOS docker host. The master branch as of today.

Steps to reproduce

1. Fix a few bugs in the sample code

2. Changed sample code to use http://127.0.0.1 instead of zipkin as hostname (or make a local host entry that points the name zipkin to 127.0.0.1)

3. Run docker-compose up -d

4. Run php ./examples/AlwaysOnTraceExample.php from your computer -- everything works! Zipkin is running!

5. Run docker-compose run --rm php php ./examples/AlwaysOnTraceExample.php or make examples, per the README.md

What is the expected behavior?

Everything works! No errors, spans/traces are send to zipkin. A new user has a good first experience with the repo.

What is the actual behavior?

I receive the following errors

Warning: file_get_contents(http://127.0.0.1:9411/api/v2/spans):
failed to open stream: Connection refused in
/usr/src/myapp/src/Exporter/ZipkinExporter.php on line 63

I was sad. I thought hard about my life choices and what I chose to get good at.

Additional context

It seems like the the provided docker-compose command executes PHP inside the container, and the php container can't talk to the zipkin container.

I'm a little uncertain on expectations here and/or if I'm missing something, so I can't suggest a solution. My end goal would be for a new user to the repository to have a successful first run experience when following the provided instructions.

Also -- re: the zipkin hostname in the sample code -- should something in docker have set this up? The README said to use 127.0.0.1 for the hostname. This is something else that would be great to clear up for new users.

We should be able to set a value within a Context object.

The spec describes this particular feature here

Success criteria - The API MUST return a new Context containing the new value.

note - We need to have #102 Completed first before we can get a value within our context object.

We should implement the Propagators API

The Spec for this API is found here

Success criteria - implement the propagators API according to the spec.

This issue is in reference to issue 398 posted on the community repository. In this issue, we are proposing that all OpenTelemetry repositories consider using GitHub Actions as their CI provider in order to maintain consistency across the various language repositories.

The overall proposal was discussed in the OpenTelemetry maintainers SIG meeting. @trask has been assigned as the mentor for the project.

The justification and benefits are enumerated in the issue on the community repository and are pasted here as well for convenience:

Proposal

We propose that all languages consider using the same CI provider. This would create a more consistent development process and make it easier for developers to contribute to multiple language libraries.

We suggest that provider be GitHub Actions. Here’s why:

Ease-of-Use

CircleCI and Travis will automatically run when pull requests and commits are issued against the repository. But if a contributor forks the repository, unless they set up an account with the CI provider and link it to their forked repository, CI will not be activated and tests will not be run automatically.
In contrast, GitHub Actions works out of the box on a forked repository and can be easily configured to run a test workflow each time a commit is issued. This would help individual contributors test their code and ensure code quality before submitting a pull request against the repository.

Transparency

Current CI providers such as CircleCI and Travis allow anyone to view the console output when building and running tests but the test results can not be seen anywhere on the GitHub repository. To view this testing output: You need go to a different website, navigate a different user interface, and then sift through thousands of lines of console output. This is not a seamless developer experience.
In contrast, using GitHub Actions would provide all testing output directly on the repository’s GitHub page, which would help contributors to find, read, and use the test output to maintain code quality.

Control

GitHub Actions’ integration with other GitHub features means you can have finer control over the CI pipeline. For example, certain workflows can be set to only run on a new release. Workflows can even be used to close stale issues and pull requests.

Recommendation

We recommend that we consider using one consistent CI provider, GitHub Actions, which provides an integrated and seamless developer experience for all contributors.

Example

Please see this example that the C++ repository has adopted for the above reasons.

Next Steps

This issue shall serve as a place for discussion about this proposal.

Could a maintainer please assign this issue to us if approved?

cc: @Brandon-Kimberly @alolita

It probably goes without saying that every OpenTelemetry library should should ship an OpenTelemetry exporter. 😄

The benefit to the PHP library in this would be that at some point, pure OpenTelemetry configurations are going to be possible, and desirable. Having an "ecosystem-native" exporter ensures that the PHP library doesn't contribute any delay towards widespread adoption.
It also helps simplify setup for newcomers by not forcing them into ecosystems and terminology outside of OpenTelemetry.

The Tracing API needs to created, using The Tracing API OpenTelemetry Specification as reference.

We'd like to replace our current time implementation with php's hrtime function.

https://www.php.net/manual/en/function.hrtime.php

Todo for this:

• update dependencies to PHP 7.3
• replace current time implementation with calls to hrtime

We would like to Implement an UpDownSumObserver Instrument for the Metrics API. The spec for the UpDownSumObserver API is defined at the following URL:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#sumobserver

the sampler bits never get used in the SDK. They are implemented and tested, but nothing currently uses them. Implement the sampler into the tracer and trace provider.

We'd like to break down the current project status.

Breakdown of features/high-level implementation status indicators. I'm going to propose the following:

✅️ - checkmarks for things that have been completed.
🔴️ - circles for things that have not been started yet.
⚠️ - warning symbols for things that are still in flux.

These should most likely be included in the README.md file

We need to implement the (newly created) resource provider:

https://github.com/open-telemetry/opentelemetry-specification/blob/27e5c89075d3eeb5981e79bf8ab94d78aea5481d/specification/resource/sdk.md#resource-sdk

This was recently added to the specification and our code should follow along with this.

We'd like to add a code of conduct.

We would like to implement an UpDownCounter Instrument for the Metrics API. The spec for the UpDownCounter API is defined at the following URL:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#updowncounter

We would like to implement a ValueRecorder Instrument for the Metrics API. The spec for the ValueRecorder API is defined at the following URL:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#valuerecorder

The SDK specs for an Alpha 0.2 release contain metrics. These are the features in scope for an Alpha 0.2 release from a metrics standpoint:

• MetricsProcessor interface
• Aggregation MetricsProcessor
• Exporter interface
• Prometheus Exporter

Success criteria : Add these features to the 0.2 Alpha release candidate.
Full SDK specs for Alpha 0.2 can be found here

We have not yet implemented Context. The spec for context can be found here

It is unclear where this should live. Python implements it in the api

The spirit of this release is to have a demo-able product that anybody can start playing with and start implementing instrumentation adaptors and data collectors for various scenarios.

Use Dmitry Krokhin's baseline for opentelemetry-php to go from zero to start in our repository:
https://github.com/basis-company/opentelemetry-php

Success criteria: Have something in the opentelemetry-php repo that isn't just a README.md

In The Initial Resource SDK PR, @lalex added the Resource SDK to Tracer and TracerProvider. The spec states:

When used with distributed tracing, a resource can be associated with the TracerProvider when it is created. That association cannot be changed later. When associated with a TracerProvider, all Spans produced by any Tracer from the provider MUST be associated with this Resource.

This issue is to track the work of associating Spans with their TracerProvider.

Because we are implicitly implementing the Context feature for OpenTelemetry-php, we need to make sure that we have the global operations that we are expected to have for the API. These operations are listed here.

This ticket specifically covers the ability to Get the current Context. this is defined here

Success criteria: The API MUST return the Context associated with the caller's current execution unit.

The Overview of the context specification explains to us what a Context is supposed to contain for the OpenTelemetry API. As far as I'm aware, PHP does not have something like this out of the box, so we'll have to implement it.

This object needs to be an immutable object, so I'd think that we would want to have a php class with a constructor and a getter, but without a setter.

This implementation should live separately from the Context API as defined in the spec.

Success criteria - being able to create a Context Object from within the code base.

We should follow the spec for the correlations API found here

Success criteria - implement the correlations API as found in the specification.

Our examples currently do not store any records to Zipkin due to malformed timestamp format caused by OpenTelemetry\Sdk\Internal\Clock

Success criteria - fix the timestamps so that we can successfully execute examples again.

We should implement a shutdown() function

The specification defines the shutdown SDK as so: shutdown

We have a placeholder defined for this in a couple places in our codebase:

• our BatchSpanProcessor, defined here
• our JaegerExporter, defined here
• our SimpleSpanProcessor, defined here
• our ZipkinExporter, defined here

Success criteria: implement a shutdown method. We should most likely start with a static shutdown timeout and determine if we eventually would like to make it end user configurable. The spec allows us to make our own determination on the timeout:

Shutdown should not block indefinitely. Language library authors can decide if they want to make the shutdown timeout configurable.

We need to implement a MeterProvider, as perscribed in:
https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#meter-provider

Success criteria - Creating a MeterProvider Implementation in the API and tying it to the eventual SDK. This part is slightly ambiguous with the documentation, so it may be best to look at other SIG implementations for inspiration.

The Propagators API needs to created, using The Propagators API OpenTelemetry Specification as reference.

@morrisonlevi mentioned we should follow the spec closely for the Span Exporter. More context here:

https://github.com/open-telemetry/opentelemetry-php/pull/18/files#diff-c41dd857f8a82514dd10ee4033caaf0aR12

Success Criteria: Following the spec for the Span Exporter.

The specification for this is ready

We should update our implementation accordingly here

Success criteria - update the shouldSample function accordingly.

Because we are implicitly implementing the Context feature for OpenTelemetry-php, we need to make sure that we have the global operations that we are expected to have for the API. These operations are listed here.

This ticket specifically covers the ability to Detach from the current Context. this is defined here

Success criteria:

The API MUST accept the following parameters:

• A Token that was returned by a previous call to attach a Context.

The API MAY return a value used to check whether the operation was successful or not.

Alpha v0.1 received a lot of feedback. As part of an Alpha release there will be a few major areas of improvement - change for out of band span reporting API and the merged pre-aggregated and non-aggregated metrics API. There are other changes as well.

We already plan for the next iteration and we know that API is expected to be changed for the Alpha v0.3 milestone. The big improvements in works are initialization and configuring logic as well as context propagation detachment.

Full API specs for Alpha 0.2 can be found here

Before opening a feature request against this repo, consider whether the feature should/could be implemented in the other OpenTelemetry client libraries. If so, please open an issue in opentelemetry-specification first.

Is your feature request related to a problem?
It is not. We'd like to have automated test suites for commits

Describe the solution you'd like
We'd like to have CI run on PR open

Describe alternatives you've considered
Manual testing

We need to implement a meter interface, as defined in:
https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#meter-interface

Success criteria: Creating a Meter Interface in the API.

Because we are implicitly implementing the Context feature for OpenTelemetry-php, we need to make sure that we have the global operations that we are expected to have for the API. These operations are listed here.

This ticket specifically covers the ability to attach to the current Context. this is defined here

Success criteria: The API MUST return a value that can be used as a Token to restore the previous Context.

We should be able to create a key within a Context object.

The spec describes this particular feature here

Success criteria - this function must return an opaque object representing the newly created key.

note - We need to have #102 Completed first before we can create a key within our context object.

The SpanKind method needs to be set in the SDK. The specification document for this lives here

Our placeholder for this function lives here

Success criteria: implementing the Span Kind function according to the specification.

We'd like to be able to export metrics to Jaeger. We can most likely use the OpenCensus php exporter Jager repo as a jumping point.

These are the features in scope for an Alpha 0.2 SDK release from a tracing standpoint:

• Built-in samplers (percentage sampler).
• SpanProcessor interface
• Batching SpanProcessor
• Exporter interface
• Jaeger and/or Zipkin exporter

Success criteria : Add these features to the 0.2 Alpha release candidate.
Full SDK specs for Alpha 0.2 can be found here

The Sampling API needs to created, using The Sampling API OpenTelemetry Specification as reference.

These are the features in scope for an Alpha 0.2 SDK release from a context propagation standpoint:

• In-process propagation
• Inject and Extract
• DistributedContext

Success criteria : Add these features to the 0.2 Alpha release candidate.
Full SDK specs for Alpha 0.2 can be found here

We should be able to get a value within a Context object.

The spec describes this particular feature here

Success criteria - The API MUST return the value in the Context for the specified key.

note - We need to have #102 Completed first before we can get a value within our context object.

The Metrics API needs to created, using The Metrics API OpenTelemetry Specification as reference.

Describe the solution you'd like
We should run static analysis on the code that we write.

Describe alternatives you've considered
None.

We would like to Implement a ValueObserver Instrument for the Metrics API. The spec for the ValueObserver API is defined at the following URL:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#valueobserver

#64 (comment)

We should be more explicit about our iterables in order to pass the correct reference.

The distributed context API needs to created, using The DistributedContext API OpenTelemetry Specification as reference.

We would like to implement a Counter Instrument for the Metrics API. The spec for the counter API is defined at the following URL:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#counter

The spirit of v0.3 release is to deliver a product with the stable, almost the release candidate level of APIs and interfaces.

After the v0.3 release of language SDKs we do expect that languages public surface may change, but we do not expect any major changes in conceptual level in specifications.

The milestone definition can be found here.

@morrisonlevi mentioned that the correct type for this Span parameter is ?SpanContext:

https://github.com/open-telemetry/opentelemetry-php/pull/18/files#diff-fb862e90b17f754862ac86b494ddb0a4R22

Success Criteria: Update the Span parameter.

We would like to Implement a SumObserver Instrument for the Metrics API. The spec for the SumObserver API is defined at the following URL:

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics/api.md#sumobserver