Redis Time Series: TS.CREATE, TS.ADD, TS.RANGE ve Sıkıştırma Kuralları

Seri oluşturmak: TS.CREATE

TS.CREATE key [RETENTION ms] [ENCODING COMPRESSED|UNCOMPRESSED] [CHUNK_SIZE bayt] [DUPLICATE_POLICY politika] [IGNORE maxZamanFarkı maxDeğerFarkı] [LABELS etiket değer ...] boş bir seri oluşturur. Anahtar zaten varsa TSDB: key already exists hatası döner. Seriyi önceden oluşturmak zorunlu değildir: TS.ADD, TS.INCRBY ve TS.DECRBY olmayan bir anahtarla çağrıldığında seriyi kendisi oluşturur.

> TS.CREATE thermometer:1
OK
> TYPE thermometer:1
TSDB-TYPE

Komut sayfasındaki örnek, sık kullanılan seçenekleri tek satırda gösterir: 60 saniyelik saklama, aynı zaman damgasında en büyük değeri tutma ve iki etiket:

> TS.CREATE temperature:2:32 RETENTION 60000 DUPLICATE_POLICY MAX LABELS sensor_id 2 area_id 32
OK

RETENTION nasıl çalışır?

Zaman damgaları, Unix başlangıcından bu yana geçen milisaniyeyi gösteren 64 bitlik tamsayılardır. RETENTION de milisaniye cinsindendir ve en önemli ayrıntısı şudur: süre sunucunun saatine göre değil, seride raporlanan en büyük zaman damgasına göre hesaplanır. Örnekler, zaman damgalarıyla sonraki TS.ADD, TS.MADD, TS.INCRBY ve TS.DECRBY çağrılarındaki zaman damgaları arasındaki farka göre düşer. Yani seriye uzun süre veri gelmezse eski örnekler silinmez. 0 değeri "hiç silme" anlamına gelir; seçenek verilmezse veritabanının genel RETENTION_POLICY ayarı kullanılır ve onun varsayılanı da 0'dır.

Bundan çıkan bir uç durum daha vardır: TS.ADD sayfasına göre, en büyük mevcut zaman damgasına göre saklama süresinden daha eski bir örnek eklemeye çalışırsanız örnek atılır ve hata döner. Geçmiş veriyi toplu yüklerken önce en yeni değeri yazarsanız, ardından gelen eski kayıtlar bu yüzden reddedilebilir.

DUPLICATE_POLICY

Aynı zaman damgasına ikinci bir örnek geldiğinde ne olacağını bu politika belirler. Varsayılan, genel ts-duplicate-policy ayarıdır ve onun varsayılanı da BLOCK değeridir.

TS.ADD içindeki ON_DUPLICATE seçeneği bu politikayı yalnızca o çağrı için geçersiz kılar. IGNORE ise politika LAST iken, sıralı gelen ve önceki örneğe hem zaman hem değer olarak çok yakın olan örnekleri tamamen yok saymayı sağlar; bu, değişmeyen sensör okumalarının seriyi şişirmesini önler.

Etiketler

Etiketler hem adı hem değeri metin olan çiftlerdir ve belgeye göre ikincil indeks görevi görür. TS.MGET, TS.MRANGE ve TS.MREVRANGE serileri etiketlerine göre seçer; TS.QUERYINDEX bir filtreye uyan tüm seri anahtarlarını döndürür. Etiketi, ölçümün kendisini değil, seriyi tanımlayan bilgiler için kullanın: konum, cihaz türü, birim gibi.

ENCODING için belge COMPRESSED seçeneğinin neredeyse her zaman doğru tercih olduğunu, belleği yaklaşık yüzde 90 azaltabildiğini ve daha az bellek erişimi nedeniyle genellikle performansı da artırdığını söyler; istisna, çok düzensiz zaman damgaları ya da değerlerdir. CHUNK_SIZE varsayılanı 4096 bayttır; emin değilseniz varsayılanı kullanmanız önerilir.

Veri eklemek: TS.ADD ve TS.MADD

TS.ADD key timestamp value bir örnek ekler ve eklenen örneğin zaman damgasını döndürür. Zaman damgası yerine * yazarsanız sunucunun saati kullanılır. Rehberdeki örnekte, seri TS.ADD sırasında 100 ms saklama süresiyle oluşturulur:

> TS.ADD thermometer:2 1 10.8 RETENTION 100
(integer) 1
> TS.ADD thermometer:3 1 10.4 LABELS location UK type Mercury
(integer) 1

RETENTION, LABELS ve DUPLICATE_POLICY gibi seçenekler TS.ADD içinde yalnızca seri yeni oluşturulurken etkilidir; var olan bir seriye örnek eklerken yok sayılır. Var olan bir serinin ayarlarını değiştirmek için TS.ALTER kullanılır.

TS.MADD tek komutta bir ya da birden fazla seriye birden çok örnek ekler ve her örnek için bir eleman döndürür. Önemli bir fark vardır: TS.ADD olmayan anahtar için seri oluştururken TS.MADD yeni seri oluşturmaz:

> TS.CREATE thermometer:1
OK
> TS.ADD thermometer:2 1 10.8
(integer) 1
> TS.MADD thermometer:1 1 9.2 thermometer:1 2 9.9 thermometer:2 2 10.3
1) (integer) 1
2) (integer) 2
3) (integer) 2

Okumak: TS.GET, TS.RANGE ve TS.REVRANGE

TS.GET en büyük zaman damgalı örneği, zaman damgası ve değer olarak döndürür:

> TS.ADD thermometer:2 1 10.8
(integer) 1
> TS.ADD thermometer:2 2 10.3
(integer) 2
> TS.GET thermometer:2
1) (integer) 2
2) 10.3

TS.RANGE key from to aralıktaki örnekleri artan zaman sırasıyla döndürür. Aralık iki uçta da kapsayıcıdır; - ve + serideki en küçük ve en büyük zaman damgasını gösterir. Ters sıra için TS.REVRANGE aynı parametrelerle kullanılır:

> TS.CREATE rg:1
OK
> TS.MADD rg:1 0 18 rg:1 1 14 rg:1 2 22 rg:1 3 18 rg:1 4 24
1) (integer) 0
2) (integer) 1
3) (integer) 2
4) (integer) 3
5) (integer) 4
> TS.RANGE rg:1 - 1
1) 1) (integer) 0
   2) 18
2) 1) (integer) 1
   2) 14
> TS.REVRANGE rg:1 - 1
1) 1) (integer) 1
   2) 14
2) 1) (integer) 0
   2) 18

İki komut da süzme yapabilir. FILTER_BY_TS yalnızca belirli zaman damgalarını, FILTER_BY_VALUE min max yalnızca kapsayıcı değer aralığındaki örnekleri bırakır; aynı değeri iki kez vererek tek bir değeri arayabilirsiniz. FILTER_BY_TS kullansanız bile zaman aralığı parametreleri yine zorunludur:

> TS.RANGE rg:1 - + FILTER_BY_TS 0 2 4
1) 1) (integer) 0
   2) 18
2) 1) (integer) 2
   2) 22
3) 1) (integer) 4
   2) 24
> TS.REVRANGE rg:1 - + FILTER_BY_TS 0 2 4 FILTER_BY_VALUE 20 25
1) 1) (integer) 4
   2) 24
2) 1) (integer) 2
   2) 22

Toplama: AGGREGATION ve kova hizalaması

Çok sık örnek eklenen bir seri hızla büyür. Belge, zaman aralığını eşit boyutlu "kovalara" bölüp her kovayı ortalama ya da en büyük değer gibi tek bir değerle temsil etmeyi önerir. Örneğin günde bir milyardan fazla örnek bekliyorsanız bir dakikalık kovalar veriyi günde 1.440 noktaya indirir. AGGREGATION toplayıcı kova_süresi eki aralık sorgularına eklenir:

> TS.CREATE rg:2
OK
> TS.MADD rg:2 0 1.8 rg:2 1 2.1 rg:2 2 2.3 rg:2 3 1.9 rg:2 4 1.78
1) (integer) 0
2) (integer) 1
3) (integer) 2
4) (integer) 3
5) (integer) 4
> TS.RANGE rg:2 - + AGGREGATION avg 2
1) 1) (integer) 0
   2) 1.9500000000000002
2) 1) (integer) 2
   2) 2.0999999999999996
3) 1) (integer) 4
   2) 1.78

Kova süresi 2 ms olduğu için beş örnek üç kovaya düşer ve son kovanın ortalaması tek bir değerden oluşur. 1.9500000000000002 gibi değerler kayan noktalı aritmetiğin doğal sonucudur; ekranda gösterirken yuvarlamanız gerekir. Kullanılabilen toplayıcılar avg, sum, min, max, range, count, first, last, std.p, std.s, var.p, var.s ve zaman ağırlıklı ortalama twa'dır. Redis 8.8 ile birden fazla toplayıcı virgülle tek sorguda istenebilir, örneğin AGGREGATION min,avg,max 2.

Kovalar nereden başlar?

Kova dizisinin bir referans zamanı vardır ve varsayılan olarak 0'dır; yani kova başlangıçları kova süresinin katlarıdır. Belgedeki örnekte 10'dan 70'e kadar her 10 ms'de bir değer vardır ve 25 ms'lik kovalarla min alınır:

> TS.RANGE sensor3 10 70 AGGREGATION min 25
1) 1) (integer) 0
   2) 1000
2) 1) (integer) 25
   2) 3000
3) 1) (integer) 50
   2) 5000
> TS.RANGE sensor3 10 70 AGGREGATION min 25 ALIGN start
1) 1) (integer) 10
   2) 1000
2) 1) (integer) 35
   2) 4000
3) 1) (integer) 60
   2) 6000

İlk sorguda kovalar 0, 25 ve 50'de başlar; sorgu 10'dan başlasa bile ilk kovanın zaman damgası 0 olarak raporlanır. ALIGN start ile kovalar sorgunun başlangıcına, yani 10'a hizalanır ve hem kova sınırları hem sonuçlar değişir: ikinci kovada artık 3000 değil 4000 en küçüktür. Raporlarınızın "saat başı" ya da "gün başı" gibi takvim sınırlarına oturması gerekiyorsa hizalamayı bilinçli seçin; aksi halde aynı veriden farklı sorgularla farklı sonuçlar alırsınız.

NaN değerleri (Redis 8.6)

Redis 8.6 ile seriler NaN değerlerini kabul eder. Bu, ölçüm alınamayan, sensörün arızalandığı ya da değerin bilinmediği zaman damgalarını, zaman yapısını bozmadan işaretlemenizi sağlar. Ham sorgular NaN değerini olduğu gibi döndürür; countNaN ve countAll dışındaki tüm toplayıcılar ise NaN değerini yok sayar:

> TS.MADD sensor:temp 1000 25.5 sensor:temp 1010 26.1 sensor:temp 1020 NaN sensor:temp 1030 24.8
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
4) (integer) 1030
> TS.RANGE sensor:temp - + AGGREGATION avg 1000
1) 1) (integer) 1000
   2) 25.466666666666665
> TS.RANGE sensor:temp - + AGGREGATION countNaN 1000
1) 1) (integer) 1000
   2) 1

Belge birkaç kısıt daha sayar: TS.INCRBY ve TS.DECRBY mevcut değer ya da işlenen NaN ise hata döndürür; FILTER_BY_VALUE sınırları NaN olamaz; IGNORE kuralında NaN asla tekrar sayılmaz; MIN, MAX ve SUM politikalarında eski ve yeni değerden yalnızca biri NaN ise hata döner. Daha eski sunucular NaN değerini kabul etmez.

Birden çok seriyi sorgulamak: TS.MGET ve TS.MRANGE

TS.MGET, TS.MRANGE ve TS.MREVRANGE anahtar adı almaz; bunun yerine bir FILTER ifadesiyle etiketlere göre seri seçer. Varsayılan olarak etiketler boş liste olarak raporlanır; WITHLABELS tümünü, SELECTED_LABELS seçtiklerinizi getirir:

> TS.CREATE rg:2 LABELS location us unit cm
OK
> TS.CREATE rg:3 LABELS location us unit in
OK
> TS.CREATE rg:4 LABELS location uk unit mm
OK

Bu üç seriye örnekler eklendikten sonra, belgedeki sorgularla ABD serilerinin son değeri birim etiketiyle, ardından santimetre ya da milimetre kullanan serilerin aralık verisi yalnızca konum etiketiyle istenir:

> TS.MGET SELECTED_LABELS unit FILTER location=us
1) 1) "rg:2"
   2) 1) 1) "unit"
         2) "cm"
   3) 1) (integer) 4
      2) 1.78
2) 1) "rg:3"
   2) 1) 1) "unit"
         2) "in"
   3) 1) (integer) 4
      2) 7.4E-1
> TS.MREVRANGE 1 3 SELECTED_LABELS location FILTER unit=(cm,mm)

7.4E-1 yazımı 0.74 değerinin bilimsel gösterimidir; istemci tarafında sayı olarak ayrıştırırken buna hazırlıklı olun. unit=(cm,mm) biçimi bir etiketin birkaç değerinden birine uyan serileri seçer. GROUPBY etiket REDUCE toplayıcı eklendiğinde sonuçlar seri başına değil etiket değeri başına gruplanır ve aynı zaman damgasındaki değerler birleştirilir; belgedeki rüzgâr örneğinde iki ülkenin serileri ülke etiketine göre gruplanıp her zaman damgası için en büyük değer alınır:

> TS.MRANGE - + FILTER country=(us,uk) GROUPBY country REDUCE max
1) 1) "country=uk"
   2) (empty array)
   3) 1) 1) (integer) 1
         2) 18
      2) 1) (integer) 2
         2) 21
      3) 1) (integer) 3
         2) 24
2) 1) "country=us"
   2) (empty array)
   3) 1) 1) (integer) 1
         2) 20
      2) 1) (integer) 2
         2) 25
      3) 1) (integer) 3
         2) 18

Sıkıştırma kuralları: TS.CREATERULE

Aynı toplama sorgusunu sürekli çalıştırmak yerine bir sıkıştırma (compaction) kuralı tanımlayabilirsiniz. Kural, kaynak seriye gelen veriyi artımlı olarak toplar ve sonuçları ayrı bir hedef seriye yazar; kaynak seri değişmez. Belgenin altını çizdiği iki koşul vardır: hedef seri kural oluşturulmadan önce var olmalıdır ve kural yalnızca oluşturulduktan sonra eklenen veriyi işler.

> TS.CREATE hyg:1
OK
> TS.CREATE hyg:compacted
OK
> TS.CREATERULE hyg:1 hyg:compacted AGGREGATION min 3
OK
> TS.MADD hyg:1 0 75 hyg:1 1 77 hyg:1 2 78
1) (integer) 0
2) (integer) 1
3) (integer) 2
> ts.range hyg:compacted - +
(empty array)
> TS.ADD hyg:1 3 79
(integer) 3
> ts.range hyg:compacted - +
1) 1) (integer) 0
   2) 75

İlk üç örnek ilk kovaya (0 ile 2 arası) düştüğü için hedef seri boştur. 3 zaman damgalı örnek yeni bir kova açınca kural önceki kovayı kapatır ve en küçük değeri (75) hedefe yazar. Kural en son kova için hedefe veri eklemez; çünkü kova süresi bitmeden toplam doğru olmaz. Ancak önceki kovalar "kilitlenmez": geç gelen bir örnek ya da silme, o kovanın sıkıştırılmış değerini yeniden günceller. Son, henüz tamamlanmamış kovanın değerini de görmek istiyorsanız aralık komutlarında LATEST seçeneği vardır. Bir yaklaşım, ham veriyi kısa bir RETENTION ile, dakikalık ya da saatlik özetleri ise uzun saklama süreli hedef serilerde tutmaktır.

Bu kuralları her seri için elle yazmak yerine genel ts-compaction-policy ayarıyla, TS.ADD ile otomatik oluşturulan yeni serilere varsayılan kurallar uygulatılabilir. Belgeye göre bu ayar TS.CREATE ile oluşturulan anahtarları etkilemez; böylece elle kurduğunuz hedef serilere istenmeyen kurallar eklenmez.

Silme ve genel ayarlar

TS.DEL key from to kapsayıcı aralıktaki örnekleri siler ve silinen sayıyı döndürür; tek bir zaman damgasını silmek için aynı değeri iki kez verirsiniz:

> TS.DEL thermometer:1 1 2
(integer) 2
> TS.DEL thermometer:1 3 3
(integer) 1

Genel varsayılanlar, Redis Open Source'ta ts- önekli yapılandırma parametreleriyle ayarlanır; örneğin ts-retention-policy, ts-duplicate-policy, ts-encoding ve ts-chunk-size-bytes. Belgedeki örnek, varsayılan saklamayı 300 gün yapar:

> CONFIG SET ts-retention-policy 25920000000

Uygulamalı mini örnek: sunucu CPU metrikleri

Birkaç sunucunun CPU kullanımını her saniye kaydettiğinizi düşünün. Komutlar belgelerdeki sözdizimine göre yazıldı; zaman damgaları sunucu saatinden geleceği için yanıtlar gösterilmiyor.

> TS.CREATE cpu:web1 RETENTION 86400000 DUPLICATE_POLICY LAST LABELS host web1 rol web
> TS.CREATE cpu:web1:dk RETENTION 2592000000 LABELS host web1 rol web ozet dakika
> TS.CREATERULE cpu:web1 cpu:web1:dk AGGREGATION avg 60000
> TS.ADD cpu:web1 * 37.5
> TS.RANGE cpu:web1 - + AGGREGATION max 300000
> TS.MGET WITHLABELS FILTER rol=web

İlk komut ham seriyi bir günlük saklama süresi ve "son gelen kazanır" politikasıyla oluşturur. İkinci komut 30 günlük saklama süreli dakikalık özet serisini, kuraldan önce oluşturur; çünkü hedef serinin önceden var olması gerekir. Üçüncü komut her dakikanın ortalamasını özete yazan kuralı ekler. Dördüncü komut sunucu saatini kullanarak bir ölçüm ekler ve kullanılan zaman damgasını döndürür. Beşinci komut beş dakikalık kovalarda en yüksek değeri verir. Son komut rol=web etiketli tüm serilerin son değerini etiketleriyle getirir; bu filtreye özet serisi de uyar, bu yüzden ham ve özet serileri ayırmak için ozet gibi ek bir etiketle filtrelemek isteyebilirsiniz. Saniyelik basit sayaçlar için INCR komutları yeterli olabilir; zaman sorgusu ve toplama gerektiğinde Time Series daha uygundur.

Sık yapılan hatalar

• RETENTION'ın sunucu saatine göre işlediğini sanmak. Süre, serideki en büyük zaman damgasına göre hesaplanır.
• Aynı zaman damgasına ikinci değer yazınca hata almak. Varsayılan politika BLOCK olduğundan bu beklenen davranıştır; DUPLICATE_POLICY ya da ON_DUPLICATE seçin.
• TS.MADD ile yeni seri yaratmaya çalışmak. TS.MADD olmayan seriyi oluşturmaz.
• Var olan seride TS.ADD ... LABELS ile etiket değiştirmeye çalışmak. Bu seçenekler yalnızca oluşturma sırasında işler; TS.ALTER kullanın.
• Hedef seriyi kuraldan sonra oluşturmak ya da geçmiş verinin sıkıştırılmasını beklemek. Hedef önce var olmalı; kural yalnızca sonraki veriyi işler.
• Kova hizalamasını gözden kaçırmak. Varsayılan referans 0'dır; sorgu başlangıcına hizalamak için ALIGN start.

Sık Sorulan Sorular

Zaman damgası saniye mi, milisaniye mi?

Milisaniyedir: Unix başlangıcından bu yana geçen milisaniyeyi gösteren 64 bitlik bir tamsayı. * sunucunun saatini kullanır.

Time Series mi, sorted set mi?

Sorted set ile zaman damgasını skor yaparak basit bir zaman dizisi kurulabilir; ancak saklama süresi, tekrar politikası, kova toplamaları, etiket filtreleri ve sıkıştırma kuralları Time Series tipinde hazır gelir. Sorted set ayrıntıları için sorted set yazısına bakabilirsiniz.

Eski verileri nasıl otomatik silerim?

Seriyi RETENTION ile oluşturun. Örnekler, serideki en yeni zaman damgasından bu süre kadar eski kaldıklarında sonraki eklemelerle düşer.

Prometheus ya da Grafana ile kullanabilir miyim?

Belge, RedisTimeSeries GitHub organizasyonunda Prometheus ve Grafana gibi araçlarla entegrasyon projeleri bulunduğunu belirtir. Bu projelerin kurulumu bu yazının kapsamı dışındadır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Redis öğrenme rehberi · Redis Array tipi · Redis Streams · Sorted set komutları · Redis 8 yenilikleri