2d:null 2e:["$","title",null,{"children":"Annotated Time Series Chart | Eric Dobbs | Observable"}] 33:T40f,## Calibration One of main challenges of working with this notebook is getting your head around three different coordinate systems: there are time coordinates embedded in the `baseimage` as labels on the x-axis, there are pixel coordinates in the `baseimage`, and there are different pixel coordinates in the screen itself. We want to describe our annotations using timestamps. Those notes must line up correctly with the times along the x-axis. We use d3's time scale to convert timestamps to image pixels. The domain is a span of datetimes chosen from labels on the x-axis. The range is the matching x coordinates of those image pixels that correspond to those chosen datetimes. When constructing your own annotated time series chart, use your own base image, and use this calibration cell to define your own `time2image()` scale. Drag over the image to move the red cursor around to find the correct x pixel coordinates from the baseimage. _Behind the scenes, the pointer position gets converted from screen pixels to image pixels._34:T577,viewof calibration = { const line = svg`` const view = html`

${baseimage.cloneNode(true)}

` update(50) function update(x) { let datetime = time2image ? time2image.invert(x) : null let date = datetime ? d3.timeFormat("%Y-%m-%d")(datetime) : "" let time = datetime ? d3.timeFormat("%H:%M%Z")(datetime) : "" line.dataset.x = x line.innerHTML = ` ${x} ${date} ${time}` } let active = false view.onmousedown = event => { active = true view.onmousemove(event) event.preventDefault() } view.onmousemove = event => { if (active) { update(Math.round(screen2image(event.layerX))) view.dispatchEvent(new CustomEvent("input")) } } view.onmouseup = event => active = false view.value = line.dataset.x return view } 35:[{"id":"f16015b83714d5a422b9281f7b2f06d8a62eddf43ce1b74096755725e5408793e282dd818d60ea873792f8e7f6bfa63d8db9a6dc5b905fea7bb03a7fd0ba998d","href":"https://static.observableusercontent.com/files/f16015b83714d5a422b9281f7b2f06d8a62eddf43ce1b74096755725e5408793e282dd818d60ea873792f8e7f6bfa63d8db9a6dc5b905fea7bb03a7fd0ba998d","name":"2021-04-honeycomb-kafka-migration.png","type":"image/png","lastModified":1646255876744.562,"size":2473795}] 31:{"id":"e1d9fca229232fcd","slug":"annotated-time-series-chart","title":"Annotated Time Series Chart","thumbnail":"965c377466c47521c1c88ed3c30fdba4baea720407bef3175c90e806806e1d36","access_level":"public","create_time":"$D2022-03-02T21:13:52.239Z","update_time":"$D2022-03-08T20:41:17.109Z","view_time":null,"first_public_time":"$D2022-03-05T22:01:02.731Z","has_unpublished_edits":null,"fork":false,"stars":2,"starred":false,"owner":{"type":"team","id":"0ab04159034289a7","login":"dobbs","name":"Eric Dobbs","avatar_url":"https://avatars-next.observableusercontent.com/b66e5674cfdf6803ebae731a2e6a4b5ac55cd6e6efdea8ab0ecddd989387ed90","tier":"starter_2024"},"version":463,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"407972836864cb3e","login":"dobbs","name":"Eric Dobbs","avatar_url":"https://avatars-next.observableusercontent.com/b66e5674cfdf6803ebae731a2e6a4b5ac55cd6e6efdea8ab0ecddd989387ed90","tier":null}],"members":[{"type":"individual","id":"407972836864cb3e","login":"dobbs","name":"Eric Dobbs","avatar_url":"https://avatars-next.observableusercontent.com/b66e5674cfdf6803ebae731a2e6a4b5ac55cd6e6efdea8ab0ecddd989387ed90","tier":null,"role":"editor"},{"type":"team","id":"0ab04159034289a7","login":"dobbs","name":"Eric Dobbs","avatar_url":"https://avatars-next.observableusercontent.com/b66e5674cfdf6803ebae731a2e6a4b5ac55cd6e6efdea8ab0ecddd989387ed90","tier":"starter_2024","role":"viewer"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"title":"Annotated Time Series Chart","cells":[{"id":0,"value":"# Annotated Time Series Chart\nSometimes the story of an incident can be told against a single time series chart. This notebook aims to do two things: we share an example to ground our interest. And we have built a tool to make it a little bit easier to create similar diagrams.\n---\nHoneycomb's [Lessons Learned From the Migration to Confluent Kafka](https://www.honeycomb.io/blog/kafka-migration-lessons-learned/) includes a motivating example. This image is a screenshot captured from the more detailed report: [pdf](https://f.hubspotusercontent30.net/hubfs/5193039/Engineering%20Retrospectives/Kafka%20Migration%20and%20Lessons%20Learned%20-%20April%202021.pdf). When we construct our own visualizations, we'll start with screenshots from dashboards in our monitoring software as our `baseimage`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":5,"value":"baseimage = FileAttachment(\"2021-04-honeycomb-kafka-migration.png\").image()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":403,"value":"baseimage.cloneNode(true)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":19,"value":"This is a perfect example. Like most time series data, this is just a bunch of wavy lines unless you know something about the system being observed. There are cliffs and spikes. Something is clearly happening. It might be normal behavior. The annotations give the reader some meaning that helps make sense of the data. In this specific case, engineers acted on the system several different times and the observed load on kafka partitions changed in response to their actions.\n\nIn this visual language, the annotations are telling us what the engineers did to the system. The position on the image and the time scale of the x-axis tell us roughly when the engineers took these actions. This is a powerful tool for communicating the complexity of an incident or for helping newcomers learn what kinds of things to look for to make sense of observablity tools.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":23,"value":"---","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":28,"value":"$33","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":109,"value":"time2image = d3.scaleTime()\n .domain([\"2020-03-09T06:00Z\", \"2020-03-10T09:00Z\"].map(Date.parse))\n .range([133, 2654])","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":34,"value":"$34","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":169,"value":"---\nOnce we have created and calibrated the `time2image()` scale, we can also use the calibration tool to describe the timestamps we want to annotate.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":412,"value":"annotations = [\n mark(\"2020-03-09T14:30Z\", \"shedding some application-side load off impacted partitions\", {\n w: 320, side: \"left\", color: \"orange\"\n }),\n mark(\"2020-03-09T19:30Z\", \"shedding more load\", {w: 100, color: \"orange\", side: \"left\"}),\n mark(\"2020-03-09T21:40Z\", \"shedding more load\", {w: 100, color: \"orange\"}),\n mark(\"2020-03-10T08:45Z\", \"rebalancing load post-recovery\", {w: 150, color: \"orange\", side: \"left\"})\n /* we'll describe the use for lane() in another notebook\n lane(\"2020-03-09T21:40Z\", \"2020-03-10T01:00Z\", {note:\"resizing ec2s\", y:70},[\n [\"2020-03-10T01:00Z\", \"2020-03-10T01:45Z\", {opacity:.5}]\n ])\n */\n]","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":173,"value":"annotatedImage = {\n const view = html`\n\n

\n ${baseimage.cloneNode(true)}\n \n

\n`\n return view\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":459,"value":"`annotationsHeight` allows us to give a little more room above the image for notes.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":261,"value":"annotationsHeight = Math.round(baseimage.height * 1.2)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":229,"value":"---\nWe offer two kinds of annotations. `mark()` adds a note to a single moment in time. `lane()` describes a span of time.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":425,"value":"markCSS = `\n .annotated svg .mark p {\n display: inline-block;\n margin: 0;\n font-size: ${screen2image(20)}px;\n }\n`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":233,"value":"function mark(when, note, {y=0, color=\"red\", side=\"right\", w=null}={}) {\n const x = time2image(new Date(when))\n const y1 = screen2image(y)\n const y2 = screen2image(annotationsHeight)\n const isRight = side == \"right\"\n const left = isRight ? \"\" : \" translateX(-100%)\"\n const pstyle = `\n color: ${color};\n transform: translate(${x}px, ${y1}px)${left};\n ${isRight ? \"\" : \"text-align: right;\"}\n ${(w == null) ? \"\" : `max-width: ${screen2image(w)}px;`}\n `.replace(/(\\n| +)/, \"\")\n return svg`\n \n \n \n

${note}

\n \n `\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":345,"value":"laneCSS = `\n .annotated svg .lane {\n display: inline-block;\n position: relative;\n transform: translate(var(--x), var(--y));\n height: ${screen2image(28)}px;\n font-size: ${screen2image(20)}px;\n }\n .annotated svg .lane time {\n display: inline-block;\n position: relative;\n height: 100%;\n }\n .annotated svg .lane time:after {\n content:'';\n position: absolute; top: 0; left: 0;\n width: 100%; height: 100%;\n background-color: var(--color);\n opacity: var(--opacity);\n }\n .annotated svg .lane span {\n display: inline-block;\n position: absolute; top:0; left: 0;\n width: 100%; height: 100%;\n text-align: center;\n }\n}`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":311,"value":"function lane(first, newer, {note=\"\", y=0, color=\"red\", opacity=0.2}={},\n [...spans]=[]) {\n const foHeight = screen2image(annotationsHeight)\n const x0 = time2image(new Date(first))\n const x1 = time2image(new Date(newer))\n const y0 = screen2image(y)\n const timespans = spans.map(([older, newer, {opacity=0.5}={}]) => {\n const sx0 = time2image(new Date(older))\n const sx1 = time2image(new Date(newer))\n return html``\n })\n return svg`\n \n

\n ${timespans}\n ${note}\n

`\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":212,"value":"`screen2image()` lets us convert from the screen pixel coordinate system to the `baseimage` pixel coordinate system. We use this in Calibration tool to help set the range for the `time2image()` scale. We also use it for setting font sizes and positioning our annotations vertically. At least for the author of this notebook, when fiddling with `marks()` and `lanes()` for the visual layout of the diagram, it is easier to think in units of the screen coordinates.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":200,"value":"screen2image = d3.scaleLinear().domain([0, width]).range([0, baseimage.naturalWidth])","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W35","stdlib":"1","titling":"auto"}} 32:"$31:body"