"""
The ray integration traces:
 - Job lifetime (job submit, job run)
 - Task submission and execution
 - Actor method submission and execution

Enabling
~~~~~~~~

Ray instrumentation is experimental. It is deactivated by default. To enable it,
you have to follow one of the two methods below:

The recommended way to instrument Ray, is to instrument the Ray cluster using ddtrace-run::

    DD_PATCH_MODULES="ray:true, aiohttp:false, grpc:false, requests:false" ddtrace-run ray start --head

DD_PATCH_MODULES will allow to reduce noise by sending only the jobs related spans.

You can also do it by starting Ray head with a tracing startup hook::

    ray start --head --tracing-startup-hook=ddtrace.contrib.ray:setup_tracing

Note that this method does not provide full tracing capabilities if ``ray.init()`` is not called at the top
of your job scripts.

Configuration
~~~~~~~~~~~~~

The Ray integration can be configured using environment variables:

- ``DD_TRACE_RAY_CORE_API``: Enable tracing of Ray's core API functions like ``ray.wait()``
    (default: ``False``)

- ``DD_TRACE_RAY_ARGS_KWARGS``: Enable tracing of arguments and keyword arguments passed to
    Ray tasks and actor methods (default: ``False``)

- ``DD_TRACE_EXPERIMENTAL_LONG_RUNNING_FLUSH_INTERVAL``: Interval for resubmitting long-running
    spans (default: ``120.0`` seconds)

- ``DD_TRACE_RAY_USE_ENTRYPOINT_AS_SERVICE_NAME``: Whether to use the job entrypoint as the
    service name (default: ``False``). If ``True``, the entrypoint will be used as the service
    name if DD_SERVICE is not set and a job name is not specified in the metadata.

- ``DD_TRACE_RAY_REDACT_ENTRYPOINT_PATHS``: Whether to redact file paths in the job entrypoint
    (default: ``True``). If ``True``, file paths in the entrypoint will be redacted to avoid
    leaking sensitive information.

Ray service name can be configured, in order of precedence by:

- specifying ``DD_SERVICE`` when initializing your Ray cluster.

- setting ``DD_TRACE_RAY_USE_ENTRYPOINT_AS_SERVICE_NAME=True``. In this case, the service
  name will be the name of your entrypoint script.

- specifying in metadata during job submission::

    ray job submit --metadata-json='{"job_name": "my_model"}' -- python entrypoint.py

By default, the service name will be ``unnamed.ray.job``.

Notes
~~~~~

- The integration disables Ray's built-in OpenTelemetry tracing to avoid duplicate telemetry.
- Actor methods like ``ping`` and ``_polling`` are excluded from tracing to reduce noise.
- Actors whose names start with an underscore (_) are not instrumented.
"""