Document that cprofile/profile only profile the main thread

[f0cc6a08-f8fc-4d78-b1be-3c701a5c623a]

BPO	38607
Nosy	@ben-spiller

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs'] title = 'Document that cprofile/profile only profile the main thread' updated_at = user = 'https://github.com/ben-spiller' ``` bugs.python.org fields: ```python activity = actor = 'benspiller' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'benspiller' dependencies = [] files = [] hgrepos = [] issue_num = 38607 keywords = [] message_count = 1.0 messages = ['355492'] nosy_count = 2.0 nosy_names = ['docs@python', 'benspiller'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue38607' versions = ['Python 3.7', 'Python 3.8', 'Python 3.9'] ```

[f0cc6a08-f8fc-4d78-b1be-3c701a5c623a]

The built-in profiling modules only provide information about the main thread (at least when invoked as documented).

To avoid user confusion we should state this in the documentation at https://docs.python.org/3/library/profile.html.

Potentially we could also suggest mitigations such as manually creating a Profile instance in the user's thread code, but the most important thing is to make clear what the module does/does not do out of the box.

(see also https://bugs.python.org/issue9609 which discusses a possible non-doc change to help with multi-threading, but looks like that's stalled, so best to push ahead with doc'ng this.

[gaogaotiantian]

As of Python 3.12, cProfile actually records the multi threading data, because it uses sys.monitoring directly. However, Profile does not because sys.setprofile is per-thread basis. I don't have a very clear opinion about which is better or how we should proceed on this.

[adamchainz]

Can we not also change Profile to use sys.monitoring? I thought the aim was to have no discrepancies between them - certainly the documentation intro lists them as “two different implementations of the same profiling interface”.

[gaogaotiantian]

We can, but I have doubts about whether I can find someone to review the code. I think by "the same profiling interface", it means they have the similar methods to use, not that they will generate the same result. And even that is not the fact anymore - for example, cProfile has the very convenient enable and disable method which Profile does not.

I think the current situation is, Profile is kind of in maintenance mode because few people are using it - the Python level profiler does not quite help due to the crazy overhead. cProfile actually is in maintenance mode as well just because that's the trend for tools - CPython team believes the fancier tools should live on pypi and the stdlib tools should only provide basic features that work across versions - and that's what cProfile does.

With so many mature profilers in the market, I'm not sure if CPython team wants to do anything to the stdlib profilers that could jeopardize backward compatibility. I might be wrong of course.