add simple documentation for ddtrace-api package

[emmettbutler]

What does this PR do? What is the motivation?

This change adds basic documentation of the ddtrace-api Python package, recently released on PyPI.

Merge instructions

Merge readiness:

• Ready for merge

Merge queue is enabled in this repo. To have it automatically merged after it receives the required reviews, create the PR (from a branch that follows the <yourname>/description naming convention) and then add the following PR comment:

/merge

Additional notes

[github-actions]

Preview links (active after the build_preview check completes)

Modified Files

• https://docs-staging.datadoghq.com/emmett.butler/dd-trace-api/tracing/trace_collection/custom_instrumentation/python/dd-api

[brett0000FF]

@emmettbutler - Very cool! Thanks for adding this content.

I am going to be OOO for the rest of the week shortly, so I wanted to share a couple high-level thoughts before I can review in more detail next week.

It seems like we could simplify this quite a bit by integrating it into the existing Datadog API page? From my quick scan, the main difference for users appears to be using from dd_trace_api import tracer instead of from ddtrace import tracer, plus installing an additional package.

The current tab structure (ddtrace-api, Datadog API, OpenTelemetry API) suggests these are parallel, alternative approaches, when ddtrace-api actually seems to be a complementary layer that works with the standard ddtrace implementation.

I might be missing certain technical context, but presenting this as a separate, duplicated documentation page might create confusion about the relationship between these packages and increase our maintenance burden when documentation needs to be updated.

[emmettbutler]

@brett0000FF making this an extension of the Datadog API tab was the first approach I considered. I chose instead to make it a separate tab to make it as clear as possible that this is an early and unstable feature. Depending on how one looks at it, dd-trace-api can also be considered a parallel integration method to ddtrace and otel. The fact that it can be used as a drop-in replacement for the ddtrace API is important to the rollout plan, because we want to avoid ever requiring users to do a hard cutover from one method to the other.

If you think it's important enough, I could replace the new tab with a paragraph at the bottom of the Datadog API tab labelled "pre-release".

[brett0000FF]

If you think it's important enough, I could replace the new tab with a paragraph at the bottom of the Datadog API tab labelled "pre-release".

@emmettbutler - I think I would be in favor of removing the separate tab for now and integrating this content into the existing DD API tab. I definitely see where you are coming from, but I think having this as a parallel tab, especially when in Preview, could create more confusion for users. Preview features are typically more hidden in the docs.

I'd be happy to take a crack at moving the content if that'd be helpful!

[brett0000FF]

@emmettbutler - Looks great, thank you! I just left a few suggestions with minor edits for readability.

[brett0000FF]

Suggested change

	<div class="alert alert-warning">The ddtrace-api Python package is in preview and may not include the API calls you need. If you'd rather use something more complete, use the API described above.
	The following steps are only necessary if you want to experiment with the preview `ddtrace-api` package.</div>
	{{< callout btn_hidden="true" header="ddtrace-api is in Preview!">}}
	The <code>ddtrace-api</code> Python package is in Preview and may not include all the API calls you need. If you need more complete functionality, use the API as described in the previous sections.
	<br><br>The following steps are only necessary if you want to experiment with the in Preview <code>ddtrace-api</code> package.{{< /callout >}}

This is our standard alert box style for features in Preview. Here's how it looks rendered:

[brett0000FF]

Suggested change

	A stable public API for Datadog APM's custom Python instrumentation is implemented by the [ddtrace-api package][8]. This package doesn't implement any of the underlying functionality that creates and
	sends spans to Datadog; it *only* implements the API interface. This separation between interface in `ddtrace-api` and implementation in `ddtrace` allows users of cusom instrumentation to rely on
	an API that changes less frequently and more predictably, while allowing autoinstrumentation-only users to ignore API changes. It also supports those users who integrate both single-step instrumentation
	and custom instrumentation by removing the need to depend on two copies of the `ddtrace` package.
	The [ddtrace-api package][8] provides a stable public API for Datadog APM's custom Python instrumentation. This package implements only the API interface, not the underlying functionality that creates and sends spans to Datadog.
	This separation between interface (`ddtrace-api`) and implementation (`ddtrace`) offers several benefits:
	- You can rely on an API that changes less frequently and more predictably for your custom instrumentation
	- If you only use automatic instrumentation, you can ignore API changes entirely
	- If you implement both single-step and custom instrumentation, you avoid depending on multiple copies of the `ddtrace` package

Just some light edits and breaking the content out.

[brett0000FF]

Suggested change

	The separation of interface and implementation means that setting up custom instrumentation requires installing two libraries: `ddtrace` as explained in the [Python Setup Instructions][6]
	and `ddtrace-api`:
	```python
	pip install 'ddtrace>=3.1' ddtrace-api
	```
	Then to instrument your Python application use the included `ddtrace-run` command. To use it, prefix your Python entry-point command with `ddtrace-run`.
	For example, if your application is started with `python app.py` then:
	```shell
	ddtrace-run python app.py
	```
	Once you've done this setup, you can write custom instrumentation just like the above examples, with `ddtrace` replaced by `dd_trace_api`. For example:
	```python
	from dd_trace_api import tracer
	@tracer.wrap(service="my-sandwich-making-svc", resource="resource_name")
	def get_ingredients():
	# go to the pantry
	# go to the fridge
	# maybe go to the store
	return
	```
	To use `ddtrace-api`:
	1. Install both the `ddtrace` and `ddtrace-api` libraries:
	```python
	pip install 'ddtrace>=3.1' ddtrace-api
	```
	2. Instrument your Python application using `ddtrace-run` by prefixing your Python entry-point command:
	```shell
	ddtrace-run python app.py
	```
	3. After this is set up, you can write custom instrumentation exactly like the examples in the previous sections, but you import from `dd_trace_api` instead of `ddtrace`.
	For example:
	```python
	from dd_trace_api import tracer
	@tracer.wrap(service="my-sandwich-making-svc", resource="resource_name")
	def get_ingredients():
	# go to the pantry
	# go to the fridge
	# maybe go to the store
	return
	```

Basically the same content, but this puts it into a numbered list.