Package: trailwatch
InstallationUsing TrailWatchDecoratorContext ManagerConnectorsAWS ConnectorSalesforce ConnectorControl Execution StatusPartial SuccessTimeoutSend a FileUsing With Other DecoratorsInstallationInstall the SDK (supports AWS server):pipinstalltrailwatchInstall with Salesforce connector support:pipinstalltrailwatch[salesforce]Using TrailWatchDecoratorThis is the recommended way to use TrailWatch. Decorator will automatically
assign job name and description based on the function name and docstring.fromtrailwatchimportconfigure,watchfromtrailwatch.connectors.awsimportAwsConnectorFactoryconfigure(project="My project name",project_description="My project description",environment="production",connectors=[AWSConnectorFactory(url="https://<random>.execute-api.us-west-2.amazonaws.com",api_key="my_key",)],loggers=["__main__","integration"],)@watch()defhandler(event,context):# Do your thingreturnContext ManagerDecorator uses this context manager internally. You can use the context manager
directly if you need more control over the execution or if you want to report a portion
of the execution (code block) as a separate job.fromtrailwatchimportconfigure,TrailwatchContextfromtrailwatch.connectors.awsimportAwsConnectorFactoryconfigure(project="My project name",project_description="My project description",environment="production",connectors=[AWSConnectorFactory(url="https://<random>.execute-api.us-west-2.amazonaws.com",api_key="my_key",)],loggers=["__main__","integration"],)defhandler(event,context):# Other codewithTrailwatchContext(job="My Job",job_description="My job description",)asexecution:# Do your thingreturn# Other codeConnectorsTwailWatch SDK works by attaching connectors to the execution context. Connectors
are responsible for tracking execution flow and for creating a record in their
respective systems. Connectors should be configured using theconfigurefunction
by provividing a list of connector factories in theconnectorsargument.AWS ConnectorAWS connector is used to send execution information to AWS TrailWatch service deployed
in client's AWS account. To use AWS connector, you will need to deploy the TrailWatch
service first and then obtain URL and API key from the service.fromtrailwatch.connectors.awsimportAwsConnectorFactoryconfigure(# Other configuration parametersconnectors=[AWSConnectorFactory(url="url",api_key="key",)],)Salesforce ConnectorSalesforce connector is used to send execution information to Kicksaw Integration App
deployed to client's Salesforce org. To use Salesforce connector, you will need to
deploy the Kicksaw Integration App first and then obtain credentials required to sign
in to the Salesforce org.fromtrailwatch.connectors.salesforceimportSalesforceConnectorFactoryconfigure(# Other configuration parametersconnectors=[SalesforceConnectorFactory(username="username",password="password",security_token="token",domain="domain",)],)Control Execution StatusPartial SuccessRaise aPartialSuccessexception to indicate that the execution was partially
successful. This exception is handled by TrailWatch to set execution status topartialand will not be propagated to the caller.fromtrailwatch.exceptionsimportPartialSuccessError@watch()defhandler(event,context):# Do your thing# You find out that only a subset of the work was successful# Log information about the failure normally using the loggerraisePartialSuccessErrorTimeoutYou can set timeout on a function to force it to stop after a certain amount of time.
This will raiseTimeoutErrorand set the execution status totimeout.:warning: When using timeout inside AWS Lambda or Azure Function you will need to
set the TrailWatch timeout to a value lower than the timeout you set on the cloud
function. Otherwise, function can timeout before TrailWatch has a chance to set the
status.@watch(timeout=10)defhandler(event,context):# Do something that takes more than 10 seconds...Or using the context manager:defhandler(event,context):withTrailwatchContext(job="My Job",job_description="My job description",timeout=10,)asexecution:# Do something that takes more than 10 seconds...Send a FileSome connectors support attaching (sending) files to be associated with the execution.
To send a file, use thesend_filemethod on theTrailwatchContextobject.
Three methods are available to send a file:send_file- send a file from the local filesystemsend_fileobj- send a file-like object (stream or open file object)send_file_content- send a file content as a string or bytesdefhandler(event,context):withTrailwatchContext(job="My Job",job_description="My job description",)asexecution:execution.send_file("my_file.txt","/path/to/my_file.txt")execution.send_fileobj("my_file.txt",open("my_file.txt","rb"))execution.send_file_content("my_file.txt","Hello from file!")When using the decorator, you will need to add an extra argumenttrailwatch_execution_contextto the function you are decorating
to receive theTrailwatchContextobject.fromtrailwatchimportTrailwatchContext@watch()defhandler(event,context,trailwatch_execution_context:TrailwatchContext):trailwatch_execution_context.send_file("my_file.txt","/path/to/my_file.txt")Connectors supporting sending files:AWS ConnectorUsing With Other DecoratorsWhen using TrailWatch with other decorators, make sure that TrailWatch decorator
is the innermost decorator. This is because TrailWatch decorator may inject
the context argument into the function and other decorators (like FastAPI) can
get confused by this argument.fromfastapiimportFastAPI,PathfrompydanticimportBaseModelapp=FastAPI()classModel(BaseModel):name:str@app.post("/my_endpoint/{resource_id}")@watch()defmy_endpoint(trailwatch_execution_context:TrailwatchContextmodel:Model,resource_id:str=Path(...,title="The ID of the resource to get"),):# Do your thingreturn