Felsöka vanliga problem med Durable Task SDK

Den här artikeln hjälper dig att diagnostisera och åtgärda vanliga problem när du skapar program med bärbara Durable Task SDK:er. Hitta ditt scenario i följande lista och följ de länkade stegen för att diagnostisera och lösa problemet.

Vanliga scenarier

Anslutning och installation

• Emulatorn körs inte eller kan inte nås
• Anslutningssträngformatet är felaktigt
• Klienten eller arbetaren kan inte ansluta
• Aktivitetshubben finns inte
• Identitetsbaserade autentiseringsfel på Azure

Orkestreringar

• Orkestreringen har stannat kvar i vänteläge
• Orkestreringen har fastnat i tillståndet 'Running'
• Nondeterministisk orchestrator-kod
• Serialiserings- och deserialiseringsfel

Aktiviteter

• Aktiviteten hittades inte
• Hantering av aktivitetsfel

gRPC

• gRPC-meddelandestorleksgränsen har överskridits
• Fel vid avbrytande av dataström under avstängning

Loggning och diagnostik

• Utförlig loggningskonfiguration
• Application Insights-integrering

Språkspecifik

• C#: Källgeneratorvarningar orsakar byggfel
• C#: Roslyn analyzer genererar foreach-loopar
• Java: Fel om nekad Gradle-behörighet
• Java: OrchestratorBlockedException
• Python: Omförsöksprincipen kräver max_retry_interval
• Python: NärAllTask-undantagsbeteende

Dessa SDK:er ansluter till Durable Task Scheduler serverdel och körs på valfri värdplattform, inklusive Azure Container Apps, Kubernetes och virtuella datorer.

Hitta problemet

Problem med anslutning och installation

Emulatorn körs inte eller kan inte nås

Om appen misslyckas vid start med ett anslutningsfel som "anslutningen nekades" eller "misslyckades att ansluta" kontrollerar du att Durable Task Scheduler-emulatorn körs och är tillgänglig.

1. Kontrollera att docker-containern för emulatorn körs:

   docker ps | grep durabletask
   

2. Kontrollera att portmappningarna är korrekta. Emulatorn exponerar två portar:

   • 8080 – gRPC-slutpunkt (används av din app)
   • 8082 – Instrumentpanelsgränssnitt

   Om du använder en anpassad portmappning uppdaterar du din reťazec pripojenia så att den matchar värdporten som mappas till containerporten 8080.

3. Testa anslutningen till gRPC-slutpunkten:

   curl -v http://localhost:8080
   

   En anslutningsavslag anger att containern inte körs eller att portmappningen är felaktig.

Anslutningssträngformatet är felaktigt

Anslutningssträngsfel är en vanlig orsak till startfel. Kontrollera att din reťazec pripojenia matchar det förväntade formatet.

Lokal utveckling (emulator):

Endpoint=http://localhost:8080;Authentication=None

Azure (hanterad identitet):

Endpoint=https://<scheduler-name>.durabletask.io;Authentication=ManagedIdentity

Azure (användartilldelad hanterad identitet):

Endpoint=https://<scheduler-name>.durabletask.io;Authentication=ManagedIdentity;ClientID=<client-id>

Vanliga misstag:

• Använda https för den lokala emulatorn (emulatorn använder http)
• Användning av http för Azure slutpunkter (Azure kräver https)
• Utelämna parametern Authentication
• Använda instrumentpanelsporten (8082) i stället för gRPC-porten (8080)

Klienten eller arbetaren kan inte ansluta

Kontrollera att klienten och arbetaren har konfigurerats med rätt anslutningssträng och uppgiftshubbens namn.

using Microsoft.DurableTask.Client.AzureManaged;
using Microsoft.DurableTask.Worker.AzureManaged;

var connectionString = "Endpoint=http://localhost:8080;Authentication=None";

var builder = Host.CreateApplicationBuilder(args);

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddOrchestrator<MyOrchestrator>();
        registry.AddActivity<MyActivity>();
    })
    .UseDurableTaskScheduler(connectionString);

builder.Services.AddDurableTaskClient()
    .UseDurableTaskScheduler(connectionString);

import {
  createAzureManagedClient,
  createAzureManagedWorkerBuilder,
} from "@microsoft/durabletask-js-azuremanaged";

const connectionString = "Endpoint=http://localhost:8080;Authentication=None";

const client = createAzureManagedClient(connectionString);
const worker = createAzureManagedWorkerBuilder(connectionString)
  .addOrchestrator(myOrchestrator)
  .addActivity(myActivity)
  .build();

from durabletask.azuremanaged.client import DurableTaskSchedulerClient
from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker

endpoint = "http://localhost:8080"
task_hub_name = "my-taskhub"

# Use token_credential=None for the local emulator
worker = DurableTaskSchedulerWorker(
    host_address=endpoint,
    taskhub=task_hub_name,
    token_credential=None,
    secure_channel=False,
)
client = DurableTaskSchedulerClient(
    host_address=endpoint,
    taskhub=task_hub_name,
    token_credential=None,
    secure_channel=False,
)

import com.microsoft.durabletask.azuremanaged.DurableTaskSchedulerClientExtensions;
import com.microsoft.durabletask.azuremanaged.DurableTaskSchedulerWorkerExtensions;

String connectionString = "Endpoint=http://localhost:8080;Authentication=None";

DurableTaskClient client = DurableTaskSchedulerClientExtensions
    .createClientBuilder(connectionString)
    .build();

DurableTaskGrpcWorker worker = DurableTaskSchedulerWorkerExtensions
    .createWorkerBuilder(connectionString)
    .addOrchestration(/* ... */)
    .addActivity(/* ... */)
    .build();

Aktivitetshubben finns inte

Om orkestreringarna inte startar eller om arbetaren ansluter men inte bearbetar arbetet kanske aktivitetshubben inte finns i schemaläggaren. Emulatorn skapar vanligtvis aktivitetshubbar automatiskt med hjälp av DTS_TASK_HUB_NAMES miljövariabeln.

Kontrollera att emulatorn startades med rätt namn på aktivitetshubben:

docker run -d -p 8080:8080 -p 8082:8082 \
  -e DTS_TASK_HUB_NAMES="my-taskhub" \
  mcr.microsoft.com/dts/dts-emulator:latest

För Azure-värdbaserade schemaläggare skapar du aktivitetshubben med hjälp av Azure CLI:

az durabletask taskhub create \
  --resource-group <resource-group> \
  --scheduler-name <scheduler-name> \
  --name <taskhub-name>

Identitetsbaserade autentiseringsfel på Azure

Om appen körs lokalt men misslyckas när den distribueras till Azure är problemet sannolikt relaterat till autentisering:

1. Kontrollera att den hanterade identiteten har tilldelats till din app (systemtilldelad eller användartilldelad).
2. Kontrollera att identiteten har rollen Durable Task Data Contributor för schemaläggarens resurs eller specifik uppgiftshubb.
3. Kontrollera att reťazec pripojenia använder rätt Authentication värde (ManagedIdentity). I Python skickar du en DefaultAzureCredential()-instans som parametern token_credential i stället för att använda en reťazec pripojenia.
4. För användartilldelade identiteter kontrollerar du att ClientID i reťazec pripojenia matchar identitetens klient-ID.

Detaljerade anvisningar finns i Konfigurera hanterad identitet för Durable Task Scheduler.

Orkestreringsproblem

Orkestreringen har fastnat i läget "Väntar"

En arbetsprocess i status "Väntar" anger att den har schemalagts men att en arbetare inte har hämtat upp den. Kontrollera följande:

• Arbetaren är igång. Kontrollera att arbetsprocessen körs och är ansluten till samma aktivitetshubb där orkestreringen schemalagts.
• Namnet på aktivitetshubben matchar. Kontrollera att både arbetaren och klienten refererar till samma namn på aktivitetshubben. Ett matchningsfel gör att arbetaren avsöker en annan aktivitetshubb.
• Orchestrator har registrerats. Den orkestreringsfunktion eller -klass som refereras vid schemaläggning måste registreras med arbetaren.

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddOrchestrator<MyOrchestrator>();
        registry.AddActivity<MyActivity>();
    })
    .UseDurableTaskScheduler(connectionString);

const worker = createAzureManagedWorkerBuilder(connectionString)
  .addOrchestrator(myOrchestrator)
  .addActivity(myActivity)
  .build();

worker.add_orchestrator(my_orchestrator)
worker.add_activity(my_activity)

workerBuilder.addOrchestration(
    new TaskOrchestrationFactory() {
        @Override
        public String getName() { return "MyOrchestrator"; }

        @Override
        public TaskOrchestration create() { return new MyOrchestrator(); }
    }
);

Orkestreringen har fastnat i tillståndet "Körs"

En orkestrering som fastnat i "Running" innebär vanligtvis att den väntar på en uppgift som inte är slutförd. Om du vill diagnostisera öppnar du instrumentpanelen Durable Task Scheduler och kontrollerar orkestreringens körningshistorik. Leta efter den senast slutförda händelsen – nästa händelse i sekvensen är den som blockerar.

Vanliga orsaker:

• Aktiviteten har inte registrerats. Orkestreringen anropar ett aktivitetsnamn som inte är registrerat hos arbetaren. Instrumentpanelen visar ett TaskScheduled-händelse utan motsvarande TaskCompleted. Kontrollera att aktivitetsnamnet matchar mellan orkestreringskoden och arbetsregistreringen (se Aktivitet hittades inte).
• Väntar på en extern händelse. Orkestreringsanropen waitForExternalEvent och händelsen har inte startats än. Instrumentpanelen visar att en EventRaised händelse förväntas men saknas. Kontrollera händelsenamnet och att avsändaren riktar in sig på rätt orkestreringsinstans-ID.
• Väntar på en hållbar timer. Orkestreringen skapar en timer som inte har upphört att gälla än. Instrumentpanelen visar en TimerCreated händelse. Vänta tills timern utlöses eller kontrollera om varaktigheten för timern är längre än förväntat.
• Aktiviteten genererar ett ohanterat undantag. Instrumentpanelen visar en TaskFailed händelse. Kontrollera detaljinformationen om felet för undantagsmeddelandet och stackspårningen.

Nondeterministisk orchestrator-kod

Orchestrator-koden måste vara deterministisk. Nondeterministisk kod orsakar omspelsfel som resulterar i oväntat beteende, oändliga loopar eller fel. Använd inte aktuell tid, slumptal, GUID eller I/O (t.ex. HTTP-anrop) direkt i orchestrator-kod. Använd de sammanhangsbaserade alternativen eller delegera till aktiviteter.

// ❌ Wrong - non-deterministic
var now = DateTime.UtcNow;
var id = Guid.NewGuid();
var data = await httpClient.GetAsync("https://example.com/api");

// ✅ Correct - deterministic
var now = context.CurrentUtcDateTime;
var id = context.NewGuid();
var data = await context.CallActivityAsync<string>("FetchData");

// ❌ Wrong - non-deterministic
const now = new Date();
const id = crypto.randomUUID();
const data = await fetch("https://example.com/api");

// ✅ Correct - deterministic
const now = ctx.currentUtcDateTime;
const id = ctx.newGuid();
const data = yield ctx.callActivity(fetchData);

# ❌ Wrong - non-deterministic
import datetime, uuid, requests
now = datetime.datetime.utcnow()
id = str(uuid.uuid4())
data = requests.get("https://example.com/api")

# ✅ Correct - deterministic
now = ctx.current_utc_datetime
id = ctx.new_uuid()
data = yield ctx.call_activity(fetch_data)

// ❌ Wrong - non-deterministic
Instant now = Instant.now();
String id = UUID.randomUUID().toString();
String data = httpClient.send(request, BodyHandlers.ofString()).body();

// ✅ Correct - deterministic
Instant now = ctx.getCurrentInstant();
String id = ctx.newUUID().toString();
String data = ctx.callActivity("FetchData", null, String.class).await();

Serialiserings- och deserialiseringsfel

Serialiseringsfel uppstår när de typer som används för orkestreringsindata, utdata eller aktivitetsresultat inte matchar mellan anroparen och den uppringda. Dessa fel kan visas som oväntade null värden, JsonException eller typecast-fel i orkestreringshistoriken.

Så här diagnostiserar du:

1. Öppna Durable Task Scheduler-instrumentpanelen och granska orkestreringshistoriken. Titta på fälten Input och Result för aktiviteter som misslyckades.
2. Kontrollera att den typ som förväntas av orkestratorn matchar den typ som returneras av aktiviteten. Om aktiviteten till exempel returnerar en string men orkestratorn förväntar sig en intmisslyckas deserialiseringen.
3. Sök efter typer som inte kan serialiseras. Anpassade typer som inte kan serialiseras till JSON (till exempel typer med cirkelreferenser eller ingen standardkonstruktor) misslyckas tyst eller utlöser undantag.

Känt problem (Java): Att skicka en String direkt till en aktivitet kan resultera i strängar med dubbla citattecken (till exempel "\"hello\"" i stället för "hello"). Det här beteendet är ett känt problem. Kasta resultatet explicit eller använd omslutningsobjekt.

Aktivitetsproblem

Aktiviteten hittades inte

Om en orkestrering misslyckas med felet "aktiviteten hittades inte" matchar inte aktivitetsnamnet som registrerats med arbetaren det namn som används i orkestreringskoden.

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddActivity<SayHello>();
    })
    .UseDurableTaskScheduler(connectionString);

string result = await context.CallActivityAsync<string>(nameof(SayHello), "Tokyo");

const sayHello = async (ctx, name) => {
  return `Hello, ${name}!`;
};

// Register with the worker
const worker = createAzureManagedWorkerBuilder(connectionString)
  .addActivity(sayHello)
  .build();

// Call from orchestrator - use the function reference
const result = yield ctx.callActivity(sayHello, "Tokyo");

def say_hello(ctx, name: str) -> str:
    return f"Hello, {name}!"

# Register with the worker
worker.add_activity(say_hello)

# Call from orchestrator - use the function reference
result = yield ctx.call_activity(say_hello, input="Tokyo")

workerBuilder.addActivity(
    new TaskActivityFactory() {
        @Override
        public String getName() { return "SayHello"; }

        @Override
        public TaskActivity create() {
            return ctx -> "Hello, " + ctx.getInput(String.class) + "!";
        }
    }
);

// Call from orchestrator
ctx.callActivity("SayHello", "Tokyo", String.class).await();

Hantering av aktivitetsfel

När en aktivitet utlöser ett undantag får orkestratorn en TaskFailedException (eller språkmotsvarighet). Fånga det här undantaget och granska den inre felinformationen för att hitta rotorsaken. I C# använder du ex.FailureDetails för att komma åt feltypen och meddelandet och IsCausedBy<T>() för att söka efter specifika undantagstyper.

Detaljerade exempel på felhantering och återförsöksprinciper på varje språk finns i Felhantering och återförsök.

gRPC-problem

gRPC-meddelandestorleksgränsen har överskridits

Om du ser ett fel av typen RESOURCE_EXHAUSTED eller message too large överskrider en orkestrering eller aktivitetsindata/utdata gRPC:s standard maximala meddelandestorlek på 4 MB.

Åtgärder:

• Minska storleken på indata och utdata. Lagra stora nyttolaster i extern lagring, till exempel Azure Blob Storage, och skicka endast referenser.
• Dela upp stora förgreningens resultat i mindre batchar som bearbetas via underordnade orkestreringar.

Fel vid annullering av dataström under nedstängning

När du stoppar en arbetare kan det uppstå CANCELLED: Cancelled on client fel. Dessa fel är vanligtvis ofarliga och uppstår eftersom gRPC-strömmen mellan arbetaren och schemaläggaren stängs under avstängningen. SDK:erna .NET, Python och Java hanterar dessa fel internt.

I JavaScript kan SDK:t utlösas Stream error Error: 1 CANCELLED: Cancelled on client när du anropar worker.stop(). Det här felet är ett känt problem. Omge ett stoppanrop med en try-catch om felet påverkar din avstängningslogik.

try {
  await worker.stop();
} catch (error) {
  // Ignore stream cancellation errors during shutdown
  if (!error.message.includes("CANCELLED")) {
    throw error;
  }
}

Loggning och diagnostik

Utförlig loggningskonfiguration

Öka loggverositeten för att få mer information om SDK-åtgärder, inklusive gRPC-kommunikation och orkestreringsreplikhändelser.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.DurableTask": "Debug"
    }
  }
}

public override async Task<string> RunAsync(
    TaskOrchestrationContext context, string input)
{
    ILogger logger = context.CreateReplaySafeLogger<MyOrchestrator>();
    logger.LogInformation("Processing input: {Input}", input);
    // ...
}

import { ConsoleLogger } from "@microsoft/durabletask-js-azuremanaged";

const worker = createAzureManagedWorkerBuilder(connectionString)
  .logger(new ConsoleLogger())
  .addOrchestrator(myOrchestrator)
  .addActivity(myActivity)
  .build();

if (!ctx.isReplaying) {
  console.log("Processing work item");
}

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("durabletask")
logger.setLevel(logging.DEBUG)

if not ctx.is_replaying:
    logger.info("Processing work item")

<!-- logback.xml -->
<configuration>
  <logger name="com.microsoft.durabletask" level="DEBUG" />
</configuration>

if (!ctx.getIsReplaying()) {
    logger.info("Processing work item");
}

Application Insights-integrering

För produktionsprogram konfigurerar du Application Insights för att samla in telemetri från ditt Durable Task SDK-program. Integreringsmetoden beror på din värdplattform:

Mer information om diagnostik finns i Diagnostik i Durable Task SDK:er.

Språkspecifika problem

C#

Källgeneratorvarningar orsakar byggfel

Om du använder <TreatWarningsAsErrors>true</TreatWarningsAsErrors> i projektet kan Durable Task källkodsgeneratorer generera varningar (CS0419, VSTHRD105) som kan orsaka att bygget misslyckas. Ignorera dessa specifika varningar:

<PropertyGroup>
  <NoWarn>$(NoWarn);CS0419;VSTHRD105</NoWarn>
</PropertyGroup>

Det här kända problemet spåras på GitHub och åtgärdas i en kommande version.

Roslyn analyzer genererar foreach-loopar

Durable Task Roslyn-analysatorn kan utlösa en ArgumentNullException när orchestrator lambda-kod är placerad i en foreach slinga. Det här beteendet är ett känt problem som inte påverkar körningsbeteendet. Uppdatera till den senaste versionen av analyspaketet för att hämta korrigeringen.

Java

Fel: nekad Gradle-åtkomst

I macOS eller Linux kan körningen ./gradlew misslyckas med ett "åtkomst nekad"-fel. Åtgärda det här felet genom att göra filen körbar:

chmod +x gradlew

OrchestratorBlockedException

Det OrchestratorBlockedException inträffar när orchestrator-koden utför en blockerande operation som SDK identifierar som potentiellt icke-deterministisk. Det här undantaget är ett skydd för att förhindra att orchestrator-kod bryter mot orchestrator-kodbegränsningar.

Vanliga orsaker:

• Anropar ett blockerande externt API i orchestrator-kod.
• Använda Thread.sleep() direkt istället för ctx.createTimer().
• Utför fil- eller nätverks-I/O i orchestrator-kod.

Flytta alla blockerings- eller I/O-åtgärder till aktiviteter.

Python

Återförsöksprincipen kräver max_retry_interval

När du konfigurerar en retry_policy i Python genererar utelämnande av parametern max_retry_interval ett fel som inte tydligt anger orsaken. Ange max_retry_intervalalltid :

from datetime import timedelta
from durabletask import task

retry_policy = task.RetryPolicy(
    max_number_of_attempts=3,
    first_retry_interval=timedelta(seconds=5),
    max_retry_interval=timedelta(minutes=1),  # Required
)

WhenAllTask-undantagsbeteende

När du använder when_all för att köra flera uppgifter parallellt, om en eller flera aktiviteter misslyckas, kanske undantagsbeteendet inte matchar förväntningarna. Endast det första undantaget utlöses och de återstående uppgiftsundantagen kan förloras. Granska enskilda aktivitetsresultat om du behöver fullständig felinformation:

tasks = [ctx.call_activity(process_item, input=item) for item in items]
try:
    results = yield task.when_all(tasks)
except TaskFailedError as e:
    # Only the first failure is raised
    # Check individual tasks for comprehensive error handling
    print(f"At least one task failed: {e}")

Få support

För frågor och rapportering av buggar öppnar du ett problem i GitHub lagringsplatsen för relevant SDK. När du rapporterar en bugg ska du inkludera:

• Påverkade orkestreringsinstans-IDn
• Tidsintervall i UTC som visar problemet
• Programnamn och distributionsregion (om det är relevant)
• SDK-version och värdplattform
• Relevanta loggar eller felmeddelanden

Relaterat innehåll

• Diagnostik i SDK:er för varaktiga uppgifter
• Instrumentpanel för Durable Task Scheduler
• Felsöka Durable Task Scheduler
• Konfigurera automatisk skalning för Durable Task SDK-appar
• OpenTelemetry-spårning för Durable Task-SDK:er