reword and rename stuff to clarify it

Author: s1gr1d

packages/core/src/types-hoist/options.ts

@@ -302,22 +302,23 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
   tracePropagationTargets?: TracePropagationTargets;
 
   /**
-   * Controls whether trace continuation should be strict about matching organization IDs.
+   * If set to `true`, the SDK will only continue a trace if the `organization ID` of the incoming trace found in the
+   * `baggage` header matches the `organization ID` of the current Sentry client.
    *
-   * When set to `true`, the SDK will only continue a trace if the organization ID in the incoming baggage
-   * matches the organization ID of the current SDK (extracted from the DSN).
+   * The client's organization ID is extracted from the DSN or can be set with the `orgId` option.
    *
-   * If there is no match, the SDK will start a new trace instead of continuing the incoming one.
+   * If the organization IDs do not match, the SDK will start a new trace instead of continuing the incoming one.
+   * This is useful to prevent traces of unknown third-party services from being continued in your application.
    *
    * @default false
    */
   strictTraceContinuation?: boolean;
 
   /**
-   * The organization ID of the current SDK. The organization ID is a string containing only numbers. This ID is used to
-   * propagate traces to other Sentry services.
+   * The organization ID for your Sentry project.
    *
-   * The SDK tries to automatically extract the organization ID from the DSN. With this option, you can override it.
+   * The SDK will try to extract the organization ID from the DSN. If it cannot be found, or if you need to override it,
+   * you can provide the ID with this option. The organization ID is used for trace propagation and for features like `strictTraceContinuation`.
    */
   orgId?: `${number}` | number;
 

packages/core/src/utils/tracing.ts

@@ -136,25 +136,25 @@ function getSampleRandFromTraceparentAndDsc(
  * See https://develop.sentry.dev/sdk/telemetry/traces/#stricttracecontinuation
  */
 export function shouldContinueTrace(client: Client, baggageOrgId?: string): boolean {
-  const sdkOptionOrgId = deriveOrgIdFromClient(client);
+  const clientOrgId = deriveOrgIdFromClient(client);
 
   // Case: baggage orgID and Client orgID don't match - always start new trace
-  if (baggageOrgId && sdkOptionOrgId && baggageOrgId !== sdkOptionOrgId) {
+  if (baggageOrgId && clientOrgId && baggageOrgId !== clientOrgId) {
     debug.log(
-      `Starting a new trace because org IDs don't match (incoming baggage: ${baggageOrgId}, SDK options: ${sdkOptionOrgId})`,
+      `Won't continue trace because org IDs don't match (incoming baggage: ${baggageOrgId}, SDK options: ${clientOrgId})`,
     );
     return false;
   }
 
   const strictTraceContinuation = client.getOptions()?.strictTraceContinuation || false; // default for `strictTraceContinuation` is `false`
 
   if (strictTraceContinuation) {
-    // With strict continuation enabled, start new trace if:
+    // With strict continuation enabled, don't continue trace if:
     // - Baggage has orgID, but Client doesn't have one
     // - Client has orgID, but baggage doesn't have one
-    if ((baggageOrgId && !sdkOptionOrgId) || (!baggageOrgId && sdkOptionOrgId)) {
+    if ((baggageOrgId && !clientOrgId) || (!baggageOrgId && clientOrgId)) {
       debug.log(
-        `Starting a new trace because strict trace continuation is enabled but one org ID is missing (incoming baggage: ${baggageOrgId}, SDK options: ${sdkOptionOrgId})`,
+        `Starting a new trace because strict trace continuation is enabled but one org ID is missing (incoming baggage: ${baggageOrgId}, Sentry client: ${clientOrgId})`,
       );
       return false;
     }