opentelemetry-php icon indicating copy to clipboard operation
opentelemetry-php copied to clipboard

Published 20 hours ago • verified publisher icon open-telemetry

Docs on opentelemetry.io

Open svrnm opened this issue 3 years ago • 3 comments
trafficstars

Hey everyone,

as someone who learned writing code with PHP centuries ago, I am happy to see all the great progress Otel PHP is making:-) I also saw that you have much more documentation these days within the repositories, and that's why I am reaching out:

The docs for PHP on opentelemetry.io are still basic, but I would like to see them grow, so I wanted to check in with you (@open-telemetry/php-approvers & @open-telemetry/php-maintainers), how you feel about building out those docs similar to what other languages have already, i.e.

  • An improved "getting started" that provides installation instructions and a quick&easy way for end-users to get a sample application instrumented
  • A page about "automatic instrumentation" (maybe not yet ready)
  • A page about "manual instrumentation" (tracer/meter init, creating spans, set attributes, events, links, later similar for metrics: https://github.com/open-telemetry/opentelemetry.io/issues/1746#issuecomment-1246929087)
  • A page about "exporters" (to stdout might be part of the getting started, some thing about OTLP, maybe jaeger,zipkin,prometheus, ...)
  • A page about "resources"
  • etc

What we can do as a first step is raising some issues with help wanted labels so people can pick this up.

cc @open-telemetry/docs-approvers

svrnm avatar Sep 29 '22 10:09 svrnm

I think all of those make sense as individual tickets! We know our documentation needs improvement; we are pushing towards beta and then we will most likely make some (much needed) improvements. GitHub issues should help with this.

bobstrecansky avatar Sep 29 '22 12:09 bobstrecansky

should we wait for beta then or should this happen in parallel?

svrnm avatar Sep 29 '22 14:09 svrnm

I would +1 on awaiting the beta.

cartermp avatar Sep 29 '22 15:09 cartermp

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

stale[bot] avatar Dec 21 '22 07:12 stale[bot]

I think it's a good time to revisit this issue, now that we've released a beta. I've improved the documentation somewhat in a recent PR which addresses a couple of the dot-points, but there's still lots to be improved upon.

brettmc avatar Dec 21 '22 08:12 brettmc

I think it's a good time to revisit this issue, now that we've released a beta. I've improved the documentation somewhat in a recent PR which addresses a couple of the dot-points, but there's still lots to be improved upon.

Agreed. The documentation is already in a good shape, but there's still a few things missing, or a few things need to be restructured:

  • Have a dedicated page for exporters (right now they are in "Getting Started")
  • Is there any API doc, if so we can link to them (see how we do it with Python, JS and other languages)
  • anything else

svrnm avatar Dec 21 '22 11:12 svrnm

anything else

These are a lower priority, but:

  • More manual instrumentation docs
  • Resources
  • Propagation that explains how libraries handle this for you

cartermp avatar Dec 21 '22 15:12 cartermp

Should there be "PHP" in the title of this issue?

chalin avatar Dec 22 '22 01:12 chalin

https://github.com/open-telemetry/opentelemetry.io/pull/2415 addresses a few of the points raised above.

brettmc avatar Feb 28 '23 03:02 brettmc