Make trace() a documented internal API

[simonw]

This should be documented so plugin authors can use it to add their own custom traces:

datasette/datasette/tracer.py

Lines 28 to 52 in 8f311d6

	@contextmanager
	def trace(type, **kwargs):
	assert not TRACE_RESERVED_KEYS.intersection(
	kwargs.keys()
	), f".trace() keyword parameters cannot include {TRACE_RESERVED_KEYS}"
	task_id = get_task_id()
	if task_id is None:
	yield
	return
	tracer = tracers.get(task_id)
	if tracer is None:
	yield
	return
	start = time.perf_counter()
	yield
	end = time.perf_counter()
	trace_info = {
	"type": type,
	"start": start,
	"end": end,
	"duration_ms": (end - start) * 1000,
	"traceback": traceback.format_list(traceback.extract_stack(limit=6)[:-3]),
	}
	trace_info.update(kwargs)
	tracer.append(trace_info)

Including the new kwargs pattern I added in #1571:

datasette/datasette/database.py

Lines 128 to 132 in f658170

	with trace(
	"sql", database=self.name, sql=sql.strip(), executemany=True
	) as kwargs:
	results, count = await self.execute_write_fn(_inner, block=block)
	kwargs["count"] = count

[simonw]

This might also be the impetus I need to bring the https://datasette.io/plugins/datasette-pretty-traces plugin into Datasette core itself.