Merge branch 'main' into otel-localized-pt

open-telemetry · Aug 22, 2024 · cd8c97a · cd8c97a
2 parents 794e341 + f691980
commit cd8c97a
Show file tree

Hide file tree

Showing 5 changed files with 286 additions and 4 deletions.
diff --git a/.github/workflows/auto-update-versions.yml b/.github/workflows/auto-update-versions.yml
@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-20.04
     if: github.repository == 'open-telemetry/opentelemetry.io'
     env:
-      DEPTH: --depth 500 # submodule clone depth
+      DEPTH: --depth 999 # submodule clone depth
 
     steps:
       - uses: actions/checkout@v4

diff --git a/.github/workflows/pr-actions.yml b/.github/workflows/pr-actions.yml
@@ -23,7 +23,7 @@ jobs:
       pull-requests: write
 
     env:
-      DEPTH: --depth 1000 # submodule clone depth
+      DEPTH: --depth 999 # submodule clone depth
 
     steps:
       - name: Extract action name

diff --git a/content/ja/docs/collector/quick-start.md b/content/ja/docs/collector/quick-start.md
@@ -0,0 +1,126 @@
+---
+title: クイックスタート
+description: コレクターをセットアップとテレメトリーの収集をすぐに始めてみましょう！
+default_lang_commit: 78f1d31
+---
+
+<!-- markdownlint-disable ol-prefix blanks-around-fences -->
+
+OpenTelemetryコレクターは、[トレース](/docs/concepts/signals/traces/)、[メトリクス](/docs/concepts/signals/metrics/)、[ログ](/docs/concepts/signals/logs/)を受け取り、テレメトリーを処理し、そのコンポーネントを使用してさまざまなオブザーバビリティバックエンドにエクスポートします。
+コレクターの概念的な概要については、[コレクター](/docs/collector)のページを参照してください。
+
+本記事でたった5分で次の内容を学習できます。
+
+- OpenTelemetryコレクターをセットアップして実行する
+- テレメトリーを送信し、コレクターによって処理されるのを確認する
+
+## 事前要件
+
+開発環境が以下の要件を満たしていることを確認してください。
+このページでは `bash` を使っていると仮定しています。
+お好みのシェルに合わせて、設定やコマンドを変更してください。
+
+- [Docker](https://www.docker.com/)、あるいは他の互換コンテナランタイム
+- [Go](https://go.dev/) 1.20以上
+- [`GOBIN` 環境変数][gobin]が設定されていること。もし設定されていなければ、適切に設定してください。次は一例です[^1]。
+  ```sh
+  export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
+  ```
+
+[^1]: 詳細については、Goの公式サイトにある[Your first program](https://go.dev/doc/code#Command)のドキュメントを参照してください。
+
+## 環境の設定
+
+1. OpenTelemetryコレクターのDockerイメージをプルします。
+
+   ```sh
+   docker pull otel/opentelemetry-collector:{{% param vers %}}
+   ```
+
+2. [telemetrygen]ユーティリティをインストールします。
+
+   ```sh
+   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
+   ```
+
+   このユーティリティは[トレース][traces]、[メトリクス][metrics]、[ログ][logs]を生成するクライアントをシミュレートできます。
+
+## テレメトリーの生成と収集
+
+3. コレクターを起動します。
+
+   ```sh
+   docker run \
+     -p 127.0.0.1:4317:4317 \
+     -p 127.0.0.1:55679:55679 \
+     otel/opentelemetry-collector:{{% param vers %}} \
+     2>&1 | tee collector-output.txt # 補足的に出力をteeして後で検索しやすくする
+   ```
+
+4. 別のターミナル窓でサンプルのトレースを生成します。
+
+   ```sh
+   $GOBIN/telemetrygen traces --otlp-insecure --traces 3
+   ```
+
+   ユーティリティによって生成された出力の中に、トレースが生成されたことのログが表示されるはずです。
+
+   ```text
+   2024-01-16T14:33:15.692-0500  INFO  traces/worker.go:99  traces generated  {"worker": 0, "traces": 3}
+   2024-01-16T14:33:15.692-0500  INFO  traces/traces.go:58  stop the batch span processor
+   ```
+
+   関連する出力を簡単に見るには、フィルタリングすると良いでしょう。
+
+   ```sh
+   $GOBIN/telemetrygen traces --otlp-insecure \
+     --traces 3 2>&1 | grep -E 'start|traces|stop'
+   ```
+
+5. コレクターコンテナを実行しているターミナル窓に、以下の例に示すようなトレースを取り込んだ様子が表示されるはずです。
+
+   ```console
+   $ grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' ./collector-output.txt
+   Span #0
+       Trace ID       : f30faffbde5fcf71432f89da1bf7bc14
+       Parent ID      : 6f1ff7f9cf4ec1c7
+       ID             : 8d1e820c1ac57337
+       Name           : okey-dokey
+       Kind           : Server
+       Start time     : 2024-01-16 14:13:54.585877 +0000 UTC
+       End time       : 2024-01-16 14:13:54.586 +0000 UTC
+       Status code    : Unset
+       Status message :
+   Span #1
+       Trace ID       : f30faffbde5fcf71432f89da1bf7bc14
+       Parent ID      :
+       ID             : 6f1ff7f9cf4ec1c7
+       Name           : lets-go
+       Kind           : Client
+       Start time     : 2024-01-16 14:13:54.585877 +0000 UTC
+       End time       : 2024-01-16 14:13:54.586 +0000 UTC
+       Status code    : Unset
+       Status message :
+   ...
+   ```
+
+6. <http://localhost:55679/debug/tracez> を開いて、表中のサンプルの1つを選択すると、先ほど生成したトレースが表示されます。
+
+7. 完了したら、たとえば<kbd>Control-C</kbd>を使用してコレクターコンテナをシャットダウンします。
+
+## この次のステップ
+
+このチュートリアルでは、OpenTelemetryコレクターを起動し、そこにテレメトリーを送信しました。
+次のステップとして、以下のことを検討してください。
+
+- [コレクターのインストール](../installation/)について別の方法を試す
+- コレクターの[デプロイ方法](../deployment/)についてさまざまな方法を学ぶ
+- コレクターの[設定](/docs/collector/configuration)ファイルとその構造を理解する
+- [レジストリ](/ecosystem/registry/?language=collector)で取得できるコンポーネントを探る
+- [OpenTelemetry Collector Builder (OCB)を使ってカスタムコレクターをビルド](/docs/collector/custom-collector/)する方法を学ぶ
+
+[gobin]: https://pkg.go.dev/cmd/go#hdr-Environment_variables
+[logs]: /docs/concepts/signals/logs/
+[metrics]: /docs/concepts/signals/metrics/
+[telemetrygen]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/cmd/telemetrygen
+[traces]: /docs/concepts/signals/traces/
diff --git a/content/pt/docs/concepts/observability-primer.md b/content/pt/docs/concepts/observability-primer.md
@@ -0,0 +1,156 @@
+---
+title: Introdução à Observabilidade
+description: Conceitos essenciais de Observabilidade
+weight: 9
+cSpell:ignore: webshop
+default_lang_commit: 6e3124135e38e749cdda15271d891813d6bc43db
+---
+
+## O que é Observabilidade? {#what-is-observability}
+
+Observabilidade permite que você compreenda um sistema de fora para dentro,
+permitindo que você faça perguntas sobre ele sem precisar conhecer seu
+funcionamento interno. Além disso, facilita a resolução de problemas e o
+tratamento de novos problemas, ou seja, "problemas desconhecidos". Também ajuda
+a responder à pergunta "Por que isso está acontecendo?"
+
+Para fazer essas perguntas sobre o seu sistema, sua aplicação deve estar
+devidamente instrumentada. Ou seja, o código da aplicação deve emitir
+[sinais](/docs/concepts/signals/) como
+[rastros](/docs/concepts/signals/traces/),
+[métricas](/docs/concepts/signals/metrics/) e
+[logs](/docs/concepts/signals/logs/). Uma aplicação está devidamente
+instrumentada quando a equipe de desenvolvimento não precisa adicionar mais
+instrumentação para solucionar um problema, pois já tem todas as informações
+necessárias.
+
+O [OpenTelemetry](/docs/what-is-opentelemetry/) é o mecanismo pelo qual o código
+da aplicação é instrumentado para ajudar a tornar um sistema observável.
+
+## Confiabilidade e métricas
+
+**Telemetria** refere-se aos dados emitidos por um sistema e seu comportamento.
+Esses dados podem vir na forma de [rastros](/docs/concepts/signals/traces/),
+[métricas](/docs/concepts/signals/metrics/) e
+[logs](/docs/concepts/signals/logs/).
+
+**Confiabilidade** responde a pergunta: "O serviço está fazendo o que os
+usuários esperam que ele faça?" Um sistema pode estar ativo 100% do tempo, mas,
+se quando um usuário clica em "Adicionar ao Carrinho" para adicionar um par de
+sapatos pretos ao carrinho de compras, o sistema nem sempre adiciona sapatos
+pretos, então o sistema pode ser **não** confiável.
+
+**Métricas** são dados numéricos sobre sua infraestrutura ou aplicação agregados
+ao longo de um período de tempo. Exemplos incluem: taxa de erro do sistema,
+utilização da CPU e taxa de requisições para um determinado serviço. Para mais
+informações sobre métricas e como elas se relacionam com o OpenTelemetry,
+consulte [Métricas](/docs/concepts/signals/metrics/).
+
+**SLI**, ou _Service Level Indicator_, representa uma medida do comportamento de
+um serviço. Um bom SLI mede seu serviço do ponto de vista dos seus usuários. Um
+exemplo de SLI pode ser a velocidade de carregamento de uma página web.
+
+**SLO**, ou _Service Level Objective_, representa a forma como confiabilidade é
+comunicada para uma organização/outras equipes. Isso é feito associando um ou
+mais SLIs ao valor de negócio.
+
+## Compreendendo rastreamento distribuído
+
+O rastreamento distribuído permite que você observe as requisições que se
+propagam por sistemas complexos e distribuídos. O rastreamento distribuído
+melhora a visibilidade da saúde da sua aplicação ou sistema, permitindo que você
+faça depurações de comportamentos difíceis de reproduzir localmente. É essencial
+para sistemas distribuídos, que costumam ter problemas não determinísticos ou
+que são muito complicados de reproduzir localmente.
+
+Para entender o rastreamento distribuído, você precisa compreender a função de
+cada um de seus componentes: logs, trechos e rastros.
+
+### Logs
+
+Um **log** é uma mensagem com registro de data e hora emitida por serviços ou
+outros componentes. Ao contrário dos [rastros](#distributed-traces), eles não
+são necessariamente associados a uma requisição de usuário ou transação
+específica. Você pode encontrar logs em praticamente todos os softwares. Logs
+foram muito utilizados no passado tanto por equipes de desenvolvimento quanto de
+operação para entender o comportamento de um sistema.
+
+Exemplo de log:
+
+```text
+I, [2021-02-23T13:26:23.505892 #22473]  INFO -- : [6459ffe1-ea53-4044-aaa3-bf902868f730] Started GET "/" for ::1 at 2021-02-23 13:26:23 -0800
+```
+
+Logs não são suficientes para rastrear a execução do código, pois geralmente não
+apresentam informações contextuais, como de onde foram chamados.
+
+Eles se tornam muito mais úteis quando incluídos como parte de um
+[trecho](#spans) ou quando são correlacionados com um rastro e um trecho.
+
+Para mais informações sobre logs e como eles se relacionam com o OpenTelemetry,
+consulte [Logs](/docs/concepts/signals/logs/).
+
+### Trechos {#spans}
+
+Um **trecho** representa uma unidade de trabalho ou operação. Trechos rastreiam
+operações específicas que uma requisição realiza, mostrando o que aconteceu
+durante o tempo em que essa operação foi executada.
+
+Um trecho contém nome, dados relacionados ao tempo,
+[mensagens de log estruturadas](/docs/concepts/signals/traces/#span-events) e
+[outros metadados (ou seja, Atributos)](/docs/concepts/signals/traces/#attributes)
+para fornecer informações sobre a operação sendo rastreada.
+
+#### Atributos de trecho
+
+Os atributos de trechos são metadados anexados a um trecho.
+
+A tabela a seguir contém exemplos de atributos de trecho:
+
+| Chave                       | Valor                                                                              |
+| :-------------------------- | :--------------------------------------------------------------------------------- |
+| `http.request.method`       | `"GET"`                                                                            |
+| `network.protocol.version`  | `"1.1"`                                                                            |
+| `url.path`                  | `"/webshop/articles/4"`                                                            |
+| `url.query`                 | `"?s=1"`                                                                           |
+| `server.address`            | `"example.com"`                                                                    |
+| `server.port`               | `8080`                                                                             |
+| `url.scheme`                | `"https"`                                                                          |
+| `http.route`                | `"/webshop/articles/:article_id"`                                                  |
+| `http.response.status_code` | `200`                                                                              |
+| `client.address`            | `"192.0.2.4"`                                                                      |
+| `client.socket.address`     | `"192.0.2.5"` (o cliente passa por um proxy)                                       |
+| `user_agent.original`       | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` |
+
+Para mais informações sobre trechos e como eles se relacionam com o
+OpenTelemetry, consulte [Trecho](/docs/concepts/signals/traces/#spans).
+
+### Rastros distribuídos {#distributed-traces}
+
+Um **rastro distribuído**, mais comumente conhecido como um **rastro**, registra
+os caminhos percorridos por requisições (feitas por uma aplicação ou usuário
+final) enquanto se propagam por arquiteturas com múltiplos serviços, como
+aplicações de microsserviços e _serverless_.
+
+Um rastro é composto de um ou mais trechos. O primeiro trecho representa o
+trecho raiz. Cada trecho raiz representa uma requisição do início ao fim. Os
+trechos abaixo do trecho raiz fornecem um contexto mais aprofundado do que
+ocorre durante uma requisição (ou quais etapas compõem uma requisição).
+
+Sem rastreamento, encontrar a causa raiz de problemas de desempenho em um
+sistema distribuído pode ser desafiador. O rastreamento torna a depuração e o
+entendimento de sistemas distribuídos menos assustador, criando um passo a passo
+do que acontece dentro de uma requisição à medida que ela flui por um sistema
+distribuído.
+
+Muitos _backends_ de Observabilidade visualizam rastros como diagramas em
+cascata que se parecem com isto:
+
+![Exemplo de Rastro](/img/waterfall-trace.svg 'Diagrama em cascata de rastreamento')
+
+Os diagramas em cascata mostram a relação pai-filho entre um trecho raiz e seus
+trechos filhos. Quando um trecho encapsula outro trecho, isso também representa
+uma relação aninhada.
+
+Para mais informações sobre rastros e como eles se relacionam com o
+OpenTelemetry, consulte [Rastros](/docs/concepts/signals/traces/).
diff --git a/package.json b/package.json
@@ -23,7 +23,7 @@
     "_filename-error": "echo 'ERROR: the following files violate naming conventions; fix using: `npm run fix:filenames`'; echo; npm run -s _ls-bad-filenames; exit 1",
     "_get:no": "echo SKIPPING get operation",
     "_get:submodule:non-lang": "npm run _get:submodule -- content-modules/opentelemetry-specification themes/docsy",
-    "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 1}",
+    "_get:submodule": "set -x && git submodule update --init ${DEPTH:- --depth 999}",
     "_hugo": "hugo --cleanDestinationDir",
     "_install:dict": "npm install -D $(npm run -s _list:dict)",
     "_install:netlify-cli": "npm list netlify-cli || npm install -O netlify-cli",
@@ -108,7 +108,7 @@
     "update:other-pkg": "npm install --save-dev gulp@latest",
     "update:pkgs": "npx npm-check-updates -u",
     "update:submodule:lang": "npm run seq -- update:submodule _get:submodule:non-lang",
-    "update:submodule": "set -x && git submodule update --remote ${DEPTH:- --depth 1}"
+    "update:submodule": "set -x && git submodule update --remote ${DEPTH:- --depth 999}"
   },
   "devDependencies": {
     "@cspell/dict-es-es": "^3.0.0",