mx-bluesky 1.5.1__py3-none-any.whl → 1.5.3__py3-none-any.whl

mx_bluesky/_version.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '1.5.1'
-__version_tuple__ = version_tuple = (1, 5, 1)
+__version__ = version = '1.5.3'
+__version_tuple__ = version_tuple = (1, 5, 3)
+
+__commit_id__ = commit_id = None

mx_bluesky/beamlines/i04/__init__.py

@@ -1,3 +1,10 @@
+from mx_bluesky.beamlines.i04.experiment_plans.i04_grid_detect_then_xray_centre_plan import (
+    i04_grid_detect_then_xray_centre,
+)
 from mx_bluesky.beamlines.i04.thawing_plan import thaw, thaw_and_stream_to_redis
 
-__all__ = ["thaw", "thaw_and_stream_to_redis"]
+__all__ = [
+    "thaw",
+    "thaw_and_stream_to_redis",
+    "i04_grid_detect_then_xray_centre",
+]

mx_bluesky/beamlines/i04/callbacks/murko_callback.py

@@ -1,6 +1,7 @@
 import copy
 import json
 from datetime import timedelta
+from typing import TypedDict
 
 from bluesky.callbacks import CallbackBase
 from dodal.log import LOGGER
@@ -8,7 +9,43 @@ from event_model.documents import Event, RunStart, RunStop
 from redis import StrictRedis
 
 
+class OmegaReading(TypedDict):
+    value: float
+    timestamp: float
+
+
+def extrapolate_omega(
+    latest_omega: OmegaReading, previous_omega: OmegaReading, image_timestamp: float
+) -> float:
+    """Extrapolate an image omega from previous omegas.
+
+    There are a number of assumptions in this calculation:
+    * The speed of the smargon is fixed
+    * The timestamps from the two different devices are synchronised and match the data
+      exactly
+
+    These are accepted to be reasonable based on larger errors likely coming from murko
+    itself and that the results ultimately will be averaged out.
+    """
+    omega_per_sec = (latest_omega["value"] - previous_omega["value"]) / (
+        latest_omega["timestamp"] - previous_omega["timestamp"]
+    )
+    time_elapsed = image_timestamp - latest_omega["timestamp"]
+    return latest_omega["value"] + time_elapsed * omega_per_sec
+
+
 class MurkoCallback(CallbackBase):
+    """A callback that triggers murko processing of images.
+
+    It combines metadata readings from e.g the goniometer rotation with the uuid's given
+    to us by an `OAVToRedisForwarder` (which describe the location of images in redis).
+    And writes these as a package to redis. A separate service then forwards this to murko.
+
+    The metadata and image data arrive independently, it is expected that the image data
+    is arriving at a faster rate than gonio metadata and so the value of omega for when
+    the image arrives is extrapolated based on previous omega readings.
+    """
+
     DATA_EXPIRY_DAYS = 7
 
     def __init__(self, redis_host: str, redis_password: str, redis_db: int = 0):
@@ -16,6 +53,7 @@ class MurkoCallback(CallbackBase):
             host=redis_host, password=redis_password, db=redis_db
         )
         self.last_uuid = None
+        self.previous_omegas: list[OmegaReading] = []
 
     def start(self, doc: RunStart) -> RunStart | None:
         self.sample_id = doc.get("sample_id")
@@ -28,14 +66,31 @@ class MurkoCallback(CallbackBase):
             "sample_id": self.sample_id,
         }
         self.last_uuid = None
+        self.previous_omegas = []
         LOGGER.info(f"Starting to stream metadata to murko under {self.sample_id}")
         return doc
 
     def event(self, doc: Event) -> Event:
         if latest_omega := doc["data"].get("smargon-omega"):
-            if self.last_uuid is not None:
+            if len(self.previous_omegas) <= 2 and self.last_uuid:
+                # For the first few images there's not enough data to extrapolate so we
+                # match them one to one
                 self.call_murko(self.last_uuid, latest_omega)
+            self.previous_omegas.append(
+                OmegaReading(
+                    value=latest_omega,
+                    timestamp=doc["timestamps"]["smargon-omega"],
+                )
+            )
         elif (uuid := doc["data"].get("oav_to_redis_forwarder-uuid")) is not None:
+            if len(self.previous_omegas) >= 2:
+                omega = extrapolate_omega(
+                    self.previous_omegas[-1],
+                    self.previous_omegas[-2],
+                    doc["timestamps"]["oav_to_redis_forwarder-uuid"],
+                )
+                LOGGER.info(f"Using extrapolated omega of {omega}")
+                self.call_murko(uuid, omega)
             self.last_uuid = uuid
         return doc
 

mx_bluesky/beamlines/i04/experiment_plans/i04_grid_detect_then_xray_centre_plan.py

@@ -0,0 +1,262 @@
+from __future__ import annotations
+
+from functools import partial
+
+import bluesky.plan_stubs as bps
+import bluesky.preprocessors as bpp
+from blueapi.core import BlueskyContext
+from bluesky.utils import MsgGenerator
+from dodal.common import inject
+from dodal.devices.aperturescatterguard import ApertureScatterguard
+from dodal.devices.attenuator.attenuator import BinaryFilterAttenuator
+from dodal.devices.backlight import Backlight
+from dodal.devices.common_dcm import BaseDCM
+from dodal.devices.detector.detector_motion import DetectorMotion
+from dodal.devices.eiger import EigerDetector
+from dodal.devices.fast_grid_scan import (
+    ZebraFastGridScan,
+    set_fast_grid_scan_params,
+)
+from dodal.devices.flux import Flux
+from dodal.devices.mx_phase1.beamstop import Beamstop
+from dodal.devices.oav.oav_detector import OAV
+from dodal.devices.oav.pin_image_recognition import PinTipDetection
+from dodal.devices.robot import BartRobot
+from dodal.devices.s4_slit_gaps import S4SlitGaps
+from dodal.devices.smargon import Smargon
+from dodal.devices.synchrotron import Synchrotron
+from dodal.devices.undulator import Undulator
+from dodal.devices.xbpm_feedback import XBPMFeedback
+from dodal.devices.zebra.zebra import Zebra
+from dodal.devices.zebra.zebra_controlled_shutter import ZebraShutter
+from dodal.devices.zocalo import ZocaloResults
+from dodal.plans.preprocessors.verify_undulator_gap import (
+    verify_undulator_gap_before_run_decorator,
+)
+
+from mx_bluesky.common.experiment_plans.common_flyscan_xray_centre_plan import (
+    BeamlineSpecificFGSFeatures,
+    construct_beamline_specific_FGS_features,
+)
+from mx_bluesky.common.experiment_plans.common_grid_detect_then_xray_centre_plan import (
+    grid_detect_then_xray_centre,
+)
+from mx_bluesky.common.experiment_plans.oav_snapshot_plan import (
+    setup_beamline_for_OAV,
+)
+from mx_bluesky.common.external_interaction.callbacks.common.zocalo_callback import (
+    ZocaloCallback,
+)
+from mx_bluesky.common.external_interaction.callbacks.xray_centre.ispyb_callback import (
+    GridscanISPyBCallback,
+)
+from mx_bluesky.common.external_interaction.callbacks.xray_centre.nexus_callback import (
+    GridscanNexusFileCallback,
+)
+from mx_bluesky.common.parameters.constants import (
+    EnvironmentConstants,
+    OavConstants,
+    PlanGroupCheckpointConstants,
+    PlanNameConstants,
+)
+from mx_bluesky.common.parameters.device_composites import (
+    GridDetectThenXRayCentreComposite,
+)
+from mx_bluesky.common.parameters.gridscan import GridCommon, SpecifiedThreeDGridScan
+from mx_bluesky.common.preprocessors.preprocessors import (
+    transmission_and_xbpm_feedback_for_collection_decorator,
+)
+from mx_bluesky.common.utils.context import device_composite_from_context
+from mx_bluesky.common.utils.log import LOGGER
+from mx_bluesky.phase1_zebra.device_setup_plans.setup_zebra import (
+    setup_zebra_for_gridscan,
+    tidy_up_zebra_after_gridscan,
+)
+
+
+def create_devices(
+    context: BlueskyContext,
+) -> GridDetectThenXRayCentreComposite:
+    return device_composite_from_context(context, GridDetectThenXRayCentreComposite)
+
+
+# See https://github.com/DiamondLightSource/blueapi/issues/506 for using device composites
+def i04_grid_detect_then_xray_centre(
+    parameters: GridCommon,
+    aperture_scatterguard: ApertureScatterguard = inject("aperture_scatterguard"),
+    attenuator: BinaryFilterAttenuator = inject("attenuator"),
+    backlight: Backlight = inject("backlight"),
+    beamstop: Beamstop = inject("beamstop"),
+    dcm: BaseDCM = inject("dcm"),
+    zebra_fast_grid_scan: ZebraFastGridScan = inject("zebra_fast_grid_scan"),
+    flux: Flux = inject("flux"),
+    oav: OAV = inject("oav"),
+    pin_tip_detection: PinTipDetection = inject("pin_tip_detection"),
+    s4_slit_gaps: S4SlitGaps = inject("s4_slit_gaps"),
+    undulator: Undulator = inject("undulator"),
+    xbpm_feedback: XBPMFeedback = inject("xbpm_feedback"),
+    zebra: Zebra = inject("zebra"),
+    robot: BartRobot = inject("robot"),
+    sample_shutter: ZebraShutter = inject("sample_shutter"),
+    eiger: EigerDetector = inject("eiger"),
+    synchrotron: Synchrotron = inject("synchrotron"),
+    zocalo: ZocaloResults = inject("zocalo"),
+    smargon: Smargon = inject("smargon"),
+    detector_motion: DetectorMotion = inject("detector_motion"),
+    oav_config: str = OavConstants.OAV_CONFIG_JSON,
+    udc: bool = False,
+) -> MsgGenerator:
+    """
+    A composite plan which:
+    - Uses the OAV to draw a virtual grid over the sample and to take snapshots of the sample
+    - Scans through the grid to identify the crystal centre
+    - Changes the aperture to match the beam size to the crystal size
+    - Moves the sample to the crystal centre of mass
+
+
+    i04's implementation of this plan is very similar to Hyperion. However, since i04
+    isn't running in a continious Bluesky UDC loop, we take additional steps in beamline
+    tidy-up.
+    """
+
+    composite = GridDetectThenXRayCentreComposite(
+        eiger,
+        synchrotron,
+        zocalo,
+        smargon,
+        aperture_scatterguard,
+        attenuator,
+        backlight,
+        beamstop,
+        dcm,
+        detector_motion,
+        zebra_fast_grid_scan,
+        flux,
+        oav,
+        pin_tip_detection,
+        s4_slit_gaps,
+        undulator,
+        xbpm_feedback,
+        zebra,
+        robot,
+        sample_shutter,
+    )
+
+    def tidy_beamline_if_not_udc():
+        if not udc:
+            yield from get_ready_for_oav_and_close_shutter(
+                composite.smargon,
+                composite.backlight,
+                composite.aperture_scatterguard,
+                composite.detector_motion,
+            )
+
+    @bpp.finalize_decorator(tidy_beamline_if_not_udc)
+    def _inner_grid_detect_then_xrc():
+        # These callbacks let us talk to ISPyB and Nexgen. They aren't included in the common plan because
+        # Hyperion handles its callbacks differently to BlueAPI-managed plans, see
+        # https://github.com/DiamondLightSource/mx-bluesky/issues/1117
+        callbacks = create_gridscan_callbacks()
+
+        @bpp.subs_decorator(callbacks)
+        @verify_undulator_gap_before_run_decorator(composite)
+        @transmission_and_xbpm_feedback_for_collection_decorator(
+            composite, parameters.transmission_frac, PlanNameConstants.GRIDSCAN_OUTER
+        )
+        def grid_detect_then_xray_centre_with_callbacks():
+            yield from grid_detect_then_xray_centre(
+                composite=composite,
+                parameters=parameters,
+                xrc_params_type=SpecifiedThreeDGridScan,
+                construct_beamline_specific=construct_i04_specific_features,
+                oav_config=oav_config,
+            )
+
+        yield from grid_detect_then_xray_centre_with_callbacks()
+
+    yield from _inner_grid_detect_then_xrc()
+
+
+def get_ready_for_oav_and_close_shutter(
+    smargon: Smargon,
+    backlight: Backlight,
+    aperture_scatterguard: ApertureScatterguard,
+    detector_motion: DetectorMotion,
+):
+    yield from bps.wait(PlanGroupCheckpointConstants.GRID_READY_FOR_DC)
+    group = "get_ready_for_oav_and_close_shutter"
+    LOGGER.info("Non-udc tidy: Seting up beamline for OAV")
+    yield from setup_beamline_for_OAV(
+        smargon, backlight, aperture_scatterguard, group=group
+    )
+    LOGGER.info("Non-udc tidy: Closing detector shutter")
+    yield from bps.abs_set(
+        detector_motion.shutter,
+        0,
+        group=group,
+    )
+    yield from bps.wait(group)
+
+
+def create_gridscan_callbacks() -> tuple[
+    GridscanNexusFileCallback, GridscanISPyBCallback
+]:
+    return (
+        GridscanNexusFileCallback(param_type=SpecifiedThreeDGridScan),
+        GridscanISPyBCallback(
+            param_type=GridCommon,
+            emit=ZocaloCallback(
+                PlanNameConstants.DO_FGS, EnvironmentConstants.ZOCALO_ENV
+            ),
+        ),
+    )
+
+
+def construct_i04_specific_features(
+    xrc_composite: GridDetectThenXRayCentreComposite,
+    xrc_parameters: SpecifiedThreeDGridScan,
+) -> BeamlineSpecificFGSFeatures:
+    """
+    Get all the information needed to do the i04 XRC flyscan.
+    """
+    signals_to_read_pre_flyscan = [
+        xrc_composite.undulator.current_gap,
+        xrc_composite.synchrotron.synchrotron_mode,
+        xrc_composite.s4_slit_gaps.xgap,
+        xrc_composite.s4_slit_gaps.ygap,
+        xrc_composite.smargon.x,
+        xrc_composite.smargon.y,
+        xrc_composite.smargon.z,
+        xrc_composite.dcm.energy_in_kev,
+    ]
+
+    signals_to_read_during_collection = [
+        xrc_composite.aperture_scatterguard,
+        xrc_composite.attenuator.actual_transmission,
+        xrc_composite.flux.flux_reading,
+        xrc_composite.dcm.energy_in_kev,
+        xrc_composite.eiger.bit_depth,
+    ]
+
+    tidy_plan = partial(
+        tidy_up_zebra_after_gridscan,
+        xrc_composite.zebra,
+        xrc_composite.sample_shutter,
+        group="flyscan_zebra_tidy",
+        wait=True,
+    )
+    set_flyscan_params_plan = partial(
+        set_fast_grid_scan_params,
+        xrc_composite.zebra_fast_grid_scan,
+        xrc_parameters.FGS_params,
+    )
+    fgs_motors = xrc_composite.zebra_fast_grid_scan
+    return construct_beamline_specific_FGS_features(
+        setup_zebra_for_gridscan,
+        tidy_plan,
+        set_flyscan_params_plan,
+        fgs_motors,
+        signals_to_read_pre_flyscan,
+        signals_to_read_during_collection,
+        get_xrc_results_from_zocalo=True,
+    )

mx_bluesky/beamlines/i24/serial/blueapi_config.yaml

@@ -7,11 +7,11 @@ env:
   events:
     broadcast_status_events: false
 api:
-  port: 25565
+  url: http://localhost:25565
   cors:
     allow_credentials: True
     origins: 
       - "*"
 stomp:
   enabled: true
-  host: i24-control.diamond.ac.uk
+  url: http://i24-control.diamond.ac.uk:61613

mx_bluesky/beamlines/i24/serial/fixed_target/i24ssx_Chip_Collect_py3v1.py

@@ -490,7 +490,9 @@ def run_aborted_plan(pmac: PMAC, dcid: DCID, exception: Exception):
         either by pressing the Abort button or because of a timeout, and to reset the \
         P variable.
     """
-    SSX_LOGGER.warning(f"Data Collection Aborted: {format_exception(exception)}")
+    SSX_LOGGER.warning(
+        f"Data Collection Aborted: {''.join(format_exception(exception))}"
+    )
     yield from bps.trigger(pmac.abort_program, wait=True)
 
     end_time = datetime.now()

mx_bluesky/common/experiment_plans/change_aperture_then_move_plan.py

@@ -4,6 +4,7 @@ from dodal.devices.aperturescatterguard import ApertureScatterguard, ApertureVal
 from dodal.devices.smargon import Smargon, StubPosition
 
 from mx_bluesky.common.device_setup_plans.manipulate_sample import move_x_y_z
+from mx_bluesky.common.parameters.constants import PlanGroupCheckpointConstants
 from mx_bluesky.common.utils.log import LOGGER
 from mx_bluesky.common.utils.tracing import TRACER
 from mx_bluesky.common.xrc_result import XRayCentreResult
@@ -43,6 +44,7 @@ def change_aperture_then_move_to_xtal(
 def set_aperture_for_bbox_mm(
     aperture_device: ApertureScatterguard,
     bbox_size_mm: list[float] | numpy.ndarray,
+    group=PlanGroupCheckpointConstants.GRID_READY_FOR_DC,
 ):
     """Sets aperture size based on bbox_size.
 
@@ -71,4 +73,6 @@ def set_aperture_for_bbox_mm(
         f"Setting aperture to {new_selected_aperture} based on bounding box size {bbox_size_mm}."
     )
 
-    yield from bps.abs_set(aperture_device.selected_aperture, new_selected_aperture)
+    yield from bps.abs_set(
+        aperture_device.selected_aperture, new_selected_aperture, group=group
+    )

mx_bluesky/common/experiment_plans/common_flyscan_xray_centre_plan.py

@@ -22,7 +22,7 @@ from mx_bluesky.common.experiment_plans.inner_plans.do_fgs import (
     ZOCALO_STAGE_GROUP,
     kickoff_and_complete_gridscan,
 )
-from mx_bluesky.common.experiment_plans.read_hardware import (
+from mx_bluesky.common.experiment_plans.inner_plans.read_hardware import (
     read_hardware_plan,
 )
 from mx_bluesky.common.parameters.constants import (
@@ -55,6 +55,25 @@ class BeamlineSpecificFGSFeatures:
     get_xrc_results_from_zocalo: bool
 
 
+def generic_tidy(xrc_composite: FlyScanEssentialDevices, wait=True) -> MsgGenerator:
+    """Tidy Zocalo and turn off Eiger dev/shm. Ran after the beamline-specific tidy plan"""
+
+    LOGGER.info("Tidying up Zocalo")
+    group = "generic_tidy"
+    # make sure we don't consume any other results
+    yield from bps.unstage(xrc_composite.zocalo, group=group)
+
+    # Turn off dev/shm streaming to avoid filling disk, see https://github.com/DiamondLightSource/hyperion/issues/1395
+    LOGGER.info("Turning off Eiger dev/shm streaming")
+    # Fix types in ophyd-async (https://github.com/DiamondLightSource/mx-bluesky/issues/855)
+    yield from bps.abs_set(
+        xrc_composite.eiger.odin.fan.dev_shm_enable,  # type: ignore
+        0,
+        group=group,
+    )
+    yield from bps.wait(group)
+
+
 def construct_beamline_specific_FGS_features(
     setup_trigger_plan: Callable[..., MsgGenerator],
     tidy_plan: Callable[..., MsgGenerator],
@@ -71,7 +90,7 @@ def construct_beamline_specific_FGS_features(
         Ran directly before kicking off the gridscan.
 
         tidy_plan (Callable): Tidy up states of devices. Ran at the end of the flyscan, regardless of
-        whether or not it finished successfully.
+        whether or not it finished successfully. Zocalo and Eiger are cleaned up separately
 
         set_flyscan_params_plan (Callable): Set PV's for the relevant Fast Grid Scan dodal device
 
@@ -135,6 +154,10 @@ def common_flyscan_xray_centre(
     There are a few other useful decorators to use with this plan, see: verify_undulator_gap_before_run_decorator, transmission_and_xbpm_feedback_for_collection_decorator
     """
 
+    def _overall_tidy():
+        yield from beamline_specific.tidy_plan()
+        yield from generic_tidy(composite)
+
     def _decorated_flyscan():
         @bpp.set_run_key_decorator(PlanNameConstants.GRIDSCAN_OUTER)
         @bpp.run_decorator(  # attach experiment metadata to the start document
@@ -146,7 +169,7 @@ def common_flyscan_xray_centre(
                 ],
             }
         )
-        @bpp.finalize_decorator(lambda: beamline_specific.tidy_plan(composite))
+        @bpp.finalize_decorator(lambda: _overall_tidy())
         def run_gridscan_and_tidy(
             fgs_composite: FlyScanEssentialDevices,
             params: SpecifiedThreeDGridScan,

mx_bluesky/common/experiment_plans/common_grid_detect_then_xray_centre_plan.py

@@ -111,6 +111,7 @@ def grid_detect_then_xray_centre(
     )
 
 
+# This function should be private but is currently called by Hyperion, see https://github.com/DiamondLightSource/mx-bluesky/issues/1148
 def detect_grid_and_do_gridscan(
     composite: GridDetectThenXRayCentreComposite,
     parameters: GridCommon,

mx_bluesky/common/experiment_plans/inner_plans/do_fgs.py

@@ -14,7 +14,9 @@ from dodal.log import LOGGER
 from dodal.plan_stubs.check_topup import check_topup_and_wait_if_necessary
 from scanspec.core import AxesPoints, Axis
 
-from mx_bluesky.common.experiment_plans.read_hardware import read_hardware_for_zocalo
+from mx_bluesky.common.experiment_plans.inner_plans.read_hardware import (
+    read_hardware_for_zocalo,
+)
 from mx_bluesky.common.parameters.constants import (
     PlanNameConstants,
 )

mx_bluesky/common/experiment_plans/oav_grid_detection_plan.py

@@ -6,6 +6,7 @@ from typing import TYPE_CHECKING
 import bluesky.plan_stubs as bps
 import numpy as np
 from blueapi.core import BlueskyContext
+from bluesky.utils import MsgGenerator
 from dodal.devices.oav.oav_detector import OAV
 from dodal.devices.oav.pin_image_recognition import PinTipDetection
 from dodal.devices.oav.pin_image_recognition.utils import NONE_VALUE
@@ -49,6 +50,16 @@ def get_min_and_max_y_of_pin(
     return min_y, max_y
 
 
+def optimum_grid_detect_angles(smargon: Smargon) -> MsgGenerator[list[float]]:
+    """We need to match the 0 and -90 that the fast grid scan performs but the order in
+    which we do the grid detection does not matter so we do the closest angle first."""
+    current_omega = yield from bps.rd(smargon.omega)
+    if current_omega < -45:
+        return [-90, 0]
+    else:
+        return [0, -90]
+
+
 def grid_detection_plan(
     composite: OavGridDetectionComposite,
     parameters: OAVParameters,
@@ -90,8 +101,7 @@ def grid_detection_plan(
 
     grid_width_pixels = int(grid_width_microns / microns_per_pixel_x)
 
-    # The FGS uses -90 so we need to match it
-    for angle in [0, -90]:
+    for angle in (yield from optimum_grid_detect_angles(smargon)):
         yield from bps.mv(smargon.omega, angle)
         # need to wait for the OAV image to update
         # See #673 for improvements

mx_bluesky/common/external_interaction/alerting/__init__.py

@@ -0,0 +1,13 @@
+from mx_bluesky.common.external_interaction.alerting._service import (
+    AlertService,
+    Metadata,
+    get_alerting_service,
+    set_alerting_service,
+)
+
+__all__ = [
+    "AlertService",
+    "Metadata",
+    "get_alerting_service",
+    "set_alerting_service",
+]

mx_bluesky/common/external_interaction/alerting/_service.py

@@ -0,0 +1,82 @@
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from typing import Protocol
+from urllib.parse import quote, urlencode
+
+
+class Metadata(StrEnum):
+    """Metadata fields that can be specified by the caller when raising an alert."""
+
+    CONTAINER = "container"
+    SAMPLE_ID = "sample_id"
+    VISIT = "visit"
+
+
+class ExtraMetadata(StrEnum):
+    """Additional metadata fields that are automatically appended by
+    the AlertService implementations."""
+
+    ALERT_CONTENT = "alert_content"
+    ALERT_SUMMARY = "alert_summary"
+    BEAMLINE = "beamline"
+    GRAYLOG_URL = "graylog_url"
+    ISPYB_URL = "ispyb_url"
+    PROPOSAL = "proposal"
+
+
+class AlertService(Protocol):
+    """
+    Implemented by any backend that provides the ability to dispatch alerts to some
+    service that is capable of disseminating them via any of a variety of media such
+    as email, SMS, instant messaging, etc etc.
+    """
+
+    def raise_alert(self, summary: str, content: str, metadata: dict[Metadata, str]):
+        """
+        Raise an alert that will be forwarded to beamline support staff, which might
+        for example be used as the basis for an incident in an incident reporting system.
+        Args:
+            summary: One line summary of the alert, that might for instance be used
+                in an email subject line.
+            content: Plain text content detailing the nature of the incident.
+            metadata: A dict of strings that can be included as metadata in the alert for
+                those backends that support it. The summary and content will be included
+                by default.
+        """
+        pass
+
+
+_alert_service: AlertService
+
+
+def get_alerting_service() -> AlertService:
+    """Get the alert service for this instance."""
+    return _alert_service
+
+
+def set_alerting_service(service: AlertService):
+    """Set the alert service for this instance, call when the beamline is initialised."""
+    global _alert_service
+    _alert_service = service
+
+
+def ispyb_url(sample_id: str):
+    return f"https://ispyb.diamond.ac.uk/samples/sid/{quote(sample_id)}"
+
+
+def graylog_url(stream_id: str):
+    now = datetime.now(UTC)
+    from_utc = now - timedelta(minutes=5)
+    from_timestamp = from_utc.isoformat()
+    # Add 1 second for graylog timing jitter
+    to_utc = now + timedelta(seconds=1)
+    to_timestamp = to_utc.isoformat()
+    query_string = urlencode(
+        {
+            "streams": stream_id,
+            "rangetype": "absolute",
+            "from": from_timestamp,
+            "to": to_timestamp,
+        }
+    )
+    return "https://graylog.diamond.ac.uk/search?" + query_string