chore(core): rename and document core APIs for clarity

Author: brettlangdon

benchmarks/core_api/scenario.py

@@ -74,7 +74,7 @@ def set_item(loops):
         def get_item(loops):
             """Measure the cost to fetch an item from the root context"""
             for _ in range(loops):
-                core.get_item("key")
+                core.find_item("key")
 
         if "core_dispatch_with_results" in self.scenario_name:
             yield core_dispatch_with_results

ddtrace/_trace/trace_handlers.py

@@ -104,50 +104,47 @@ def __getattribute__(self, name):
 def _get_parameters_for_new_span_directly_from_context(ctx: core.ExecutionContext) -> Dict[str, Any]:
     span_kwargs = {}
     for parameter_name in {"span_type", "resource", "service", "child_of", "activate"}:
-        parameter_value = ctx.get_local_item(parameter_name)
+        parameter_value = ctx.get_item(parameter_name)
         if parameter_value:
             span_kwargs[parameter_name] = parameter_value
     return span_kwargs
 
 
 def _start_span(ctx: core.ExecutionContext, call_trace: bool = True, **kwargs) -> "Span":
-    activate_distributed_headers = ctx.get_local_item("activate_distributed_headers")
+    activate_distributed_headers = ctx.get_item("activate_distributed_headers")
     span_kwargs = _get_parameters_for_new_span_directly_from_context(ctx)
-    call_trace = ctx.get_local_item("call_trace", call_trace)
+    call_trace = ctx.get_item("call_trace", call_trace)
     # Look for the tracer in the context, or fallback to the global tracer
-    tracer = (
-        ctx.get_local_item("tracer")
-        or (ctx.get_local_item("middleware") or ctx.get_local_item("pin") or ddtrace).tracer
-    )
-    integration_config = ctx.get_local_item("integration_config")
+    tracer = ctx.get_item("tracer") or (ctx.get_item("middleware") or ctx.get_item("pin") or ddtrace).tracer
+    integration_config = ctx.get_item("integration_config")
     if integration_config and activate_distributed_headers:
         trace_utils.activate_distributed_headers(
             tracer,
             int_config=integration_config,
-            request_headers=ctx.get_local_item("distributed_headers"),
-            override=ctx.get_local_item("distributed_headers_config_override"),
+            request_headers=ctx.get_item("distributed_headers"),
+            override=ctx.get_item("distributed_headers_config_override"),
         )
-    distributed_context = ctx.get_local_item("distributed_context")
+    distributed_context = ctx.get_item("distributed_context")
     if distributed_context and not call_trace:
         span_kwargs["child_of"] = distributed_context
 
     if config._inferred_proxy_services_enabled:
         # dispatch event for checking headers and possibly making an inferred proxy span
         core.dispatch("inferred_proxy.start", (ctx, tracer, span_kwargs, call_trace, integration_config))
         # re-get span_kwargs in case an inferred span was created and we have a new span_kwargs.child_of field
-        span_kwargs = ctx.get_local_item("span_kwargs", span_kwargs)
+        span_kwargs = ctx.get_item("span_kwargs", span_kwargs)
 
     span_kwargs.update(kwargs)
-    span_name = ctx.get_local_item("span_name")
+    span_name = ctx.get_item("span_name")
     if not span_name:
         raise ValueError("span_name must be set in the context before starting a span")
     span = (tracer.trace if call_trace else tracer.start_span)(span_name, **span_kwargs)
 
-    tags: Optional[Dict[str, str]] = ctx.get_local_item("tags")
+    tags: Optional[Dict[str, str]] = ctx.get_item("tags")
     if tags:
         for tk, tv in tags.items():
             span.set_tag(tk, tv)
-    if ctx.get_local_item("measured"):
+    if ctx.get_item("measured"):
         # PERF: avoid setting via Span.set_tag
         span.set_metric(_SPAN_MEASURED_KEY, 1)
 
@@ -175,7 +172,7 @@ def _finish_span(
     exc_type, exc_value, exc_traceback = exc_info
     if exc_type and exc_value and exc_traceback:
         span.set_exc_info(exc_type, exc_value, exc_traceback)
-    elif ctx.get_local_item("should_set_traceback", False):
+    elif ctx.get_item("should_set_traceback", False):
         span.set_traceback()
     span.finish()
 
@@ -197,7 +194,7 @@ def _on_web_framework_start_request(ctx, int_config):
 def _on_web_framework_finish_request(
     span, int_config, method, url, status_code, query, req_headers, res_headers, route, finish, **kwargs
 ):
-    if core.get_local_item("set_resource", default=False) is True and status_code is not None:
+    if core.get_item("set_resource", default=False) is True and status_code is not None:
         try:
             status_code = int(status_code)
         except ValueError:
@@ -216,7 +213,7 @@ def _on_web_framework_finish_request(
         **kwargs,
     )
     _set_inferred_proxy_tags(span, status_code)
-    for tk, tv in core.get_local_item("additional_tags", default=dict()).items():
+    for tk, tv in core.get_item("additional_tags", default=dict()).items():
         span.set_tag_str(tk, tv)
 
     if finish:
@@ -294,18 +291,18 @@ def _on_traced_request_context_started_flask(ctx):
 
 
 def _maybe_start_http_response_span(ctx: core.ExecutionContext) -> None:
-    request_span = ctx.get_local_item("request_span")
-    middleware = ctx.get_local_item("middleware")
-    status_code, status_msg = ctx.get_local_item("status").split(" ", 1)
+    request_span = ctx.get_item("request_span")
+    middleware = ctx.get_item("middleware")
+    status_code, status_msg = ctx.get_item("status").split(" ", 1)
     trace_utils.set_http_meta(
-        request_span, middleware._config, status_code=status_code, response_headers=ctx.get_local_item("environ")
+        request_span, middleware._config, status_code=status_code, response_headers=ctx.get_item("environ")
     )
-    if ctx.get_local_item("start_span", False):
+    if ctx.get_item("start_span", False):
         request_span.set_tag_str(http.STATUS_MSG, status_msg)
         _start_span(
             ctx,
             call_trace=False,
-            child_of=ctx.get_local_item("parent_call"),
+            child_of=ctx.get_item("parent_call"),
             activate=True,
         )
 
@@ -522,7 +519,7 @@ def _on_request_span_modifier_post(ctx, flask_config, request, req_body):
 
 
 def _on_traced_get_response_pre(_, ctx: core.ExecutionContext, request, before_request_tags):
-    before_request_tags(ctx.get_local_item("pin"), ctx.span, request)
+    before_request_tags(ctx.get_item("pin"), ctx.span, request)
     ctx.span._metrics[_SPAN_MEASURED_KEY] = 1
 
 
@@ -567,7 +564,7 @@ def _on_django_cache(
     exc_info: Tuple[Optional[type], Optional[BaseException], Optional[TracebackType]],
 ) -> None:
     try:
-        rowcount = ctx.get_local_item("rowcount")
+        rowcount = ctx.get_item("rowcount")
         if rowcount is not None:
             ctx.span.set_metric(db.ROWCOUNT, rowcount)
     finally:
@@ -610,8 +607,8 @@ def _on_django_after_request_headers_post(
         response_headers=response_headers,
         request_cookies=request.COOKIES,
         request_path_params=request.resolver_match.kwargs if request.resolver_match is not None else None,
-        peer_ip=core.get_local_item("http.request.remote_ip"),
-        headers_are_case_sensitive=bool(core.get_local_item("http.request.headers_case_sensitive")),
+        peer_ip=core.get_item("http.request.remote_ip"),
+        headers_are_case_sensitive=bool(core.get_item("http.request.headers_case_sensitive")),
         response_cookies=response_cookies,
     )
 
@@ -756,7 +753,7 @@ def _on_botocore_bedrock_process_response_converse(
     ctx: core.ExecutionContext,
     result: List[Dict[str, Any]],
 ):
-    ctx.get_local_item("bedrock_integration").llmobs_set_tags(
+    ctx.get_item("bedrock_integration").llmobs_set_tags(
         ctx.span,
         args=[ctx],
         kwargs={},
@@ -770,8 +767,8 @@ def _on_botocore_bedrock_process_response(
     formatted_response: Dict[str, Any],
 ) -> None:
     with ctx.span as span:
-        model_name = ctx.get_local_item("model_name")
-        integration = ctx.get_local_item("bedrock_integration")
+        model_name = ctx.get_item("model_name")
+        integration = ctx.get_item("bedrock_integration")
         if "embed" in model_name:
             return
         integration.llmobs_set_tags(span, args=[ctx], kwargs={}, response=formatted_response)
@@ -914,7 +911,7 @@ def _on_azure_servicebus_send_message_modifier(ctx, azure_servicebus_config, ent
 
 
 def _on_router_match(route):
-    req_span = core.get_local_item("req_span")
+    req_span = core.get_item("req_span")
     core.set_item("set_resource", False)
     req_span.resource = "{} {}".format(
         route.method,

ddtrace/appsec/_asm_request_context.py

@@ -108,11 +108,11 @@ def __init__(self, span: Optional[Span] = None, rc_products: str = ""):
 
 
 def _get_asm_context() -> Optional[ASM_Environment]:
-    return core.get_item(_ASM_CONTEXT)
+    return core.find_item(_ASM_CONTEXT)
 
 
 def in_asm_context() -> bool:
-    return core.get_item(_ASM_CONTEXT) is not None
+    return core.find_item(_ASM_CONTEXT) is not None
 
 
 def is_blocked() -> bool:
@@ -530,10 +530,10 @@ def start_context(span: Span, rc_products: str):
         # it should only be called at start of a core context, when ASM_Env is not set yet
         core.set_item(_ASM_CONTEXT, ASM_Environment(span=span, rc_products=rc_products))
         asm_request_context_set(
-            core.get_local_item("remote_addr"),
-            core.get_local_item("headers"),
-            core.get_local_item("headers_case_sensitive"),
-            core.get_local_item("block_request_callable"),
+            core.get_item("remote_addr"),
+            core.get_item("headers"),
+            core.get_item("headers_case_sensitive"),
+            core.get_item("block_request_callable"),
         )
 
 

ddtrace/appsec/_handlers.py

@@ -375,13 +375,13 @@ def _asgi_make_block_content(ctx, url):
 
 def _on_flask_blocked_request(span):
     span.set_tag_str(http.STATUS_CODE, "403")
-    request = core.get_item("flask_request")
+    request = core.find_item("flask_request")
     try:
         base_url = getattr(request, "base_url", None)
         query_string = getattr(request, "query_string", None)
         if base_url and query_string:
-            _set_url_tag(core.get_item("flask_config"), span, base_url, query_string)
-        if query_string and core.get_item("flask_config").trace_query_string:
+            _set_url_tag(core.find_item("flask_config"), span, base_url, query_string)
+        if query_string and core.find_item("flask_config").trace_query_string:
             span.set_tag_str(http.QUERY_STRING, query_string)
         if request.method is not None:
             span.set_tag_str(http.METHOD, request.method)

ddtrace/appsec/_iast/_handlers.py

@@ -190,7 +190,7 @@ def _on_django_middleware(ctx: core.ExecutionContext, call_trace: bool = True, *
     if not asm_config._iast_enabled or not asm_config.is_iast_request_enabled:
         return
 
-    request = ctx.get_item("request")
+    request = ctx.find_item("request")
     if request:
         args = (request,)
         _taint_django_func_call(request, args, {})

ddtrace/appsec/_iast/_iast_env.py

@@ -44,8 +44,8 @@ def endpoint_key(self) -> str:
 
 
 def _get_iast_env() -> Optional[IASTEnvironment]:
-    return core.get_item(IAST.REQUEST_CONTEXT_KEY)
+    return core.find_item(IAST.REQUEST_CONTEXT_KEY)
 
 
 def in_iast_env() -> bool:
-    return core.get_item(IAST.REQUEST_CONTEXT_KEY) is not None
+    return core.find_item(IAST.REQUEST_CONTEXT_KEY) is not None

ddtrace/appsec/_processor.py

@@ -197,7 +197,7 @@ def on_span_start(self, span: Span) -> None:
             return
 
         if span.span_type == SpanTypes.SERVERLESS:
-            skip_event = core.get_item("appsec_skip_next_lambda_event")
+            skip_event = core.find_item("appsec_skip_next_lambda_event")
             if skip_event:
                 core.discard_item("appsec_skip_next_lambda_event")
                 log.debug(

ddtrace/contrib/internal/botocore/services/bedrock.py

@@ -332,7 +332,7 @@ def _extract_streamed_response(ctx: core.ExecutionContext, streamed_body: List[D
         elif provider == _COHERE:
             if "is_finished" in streamed_body[0]:  # streamed response
                 if "index" in streamed_body[0]:  # n >= 2
-                    num_generations = int(ctx.get_item("num_generations") or 0)
+                    num_generations = int(ctx.find_item("num_generations") or 0)
                     text = [
                         "".join([chunk["text"] for chunk in streamed_body[:-1] if chunk["index"] == i])
                         for i in range(num_generations)

ddtrace/contrib/internal/botocore/services/stepfunctions.py

@@ -36,7 +36,7 @@ def update_stepfunction_input(ctx: core.ExecutionContext, params: Any) -> None:
 
     input_obj["_datadog"] = {}
     core.dispatch("botocore.stepfunctions.update_input", [ctx, None, None, input_obj, None])
-    updated_input_obj = ctx.get_item(BOTOCORE_STEPFUNCTIONS_INPUT_KEY)
+    updated_input_obj = ctx.find_item(BOTOCORE_STEPFUNCTIONS_INPUT_KEY)
     if updated_input_obj:
         input_json_str = json.dumps(updated_input_obj)
         params["input"] = input_json_str

ddtrace/contrib/internal/celery/app.py

@@ -126,13 +126,13 @@ def _traced_apply_async_inner(func, instance, args, kwargs):
             except Exception:
                 # If an internal exception occurs, record the exception in the span,
                 # then raise the Celery error as usual
-                task_span = core.get_item("task_span")
+                task_span = core.find_item("task_span")
                 if task_span:
                     task_span.set_exc_info(*sys.exc_info())
 
                 raise
             finally:
-                task_span = core.get_item("task_span")
+                task_span = core.find_item("task_span")
                 if task_span:
                     log.debug(
                         "The after_task_publish signal was not called, so manually closing span: %r",